Feature/skill creation docs

.github/workflows/verify-examples.yml

@@ -0,0 +1,17 @@
+name: verify-examples
+
+on:
+  push:
+    branches: [master, develop]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Verify every good example against its source root
+        run: bash scripts/verify-examples.sh

README.md

@@ -81,6 +81,7 @@ Pure Python stdlib — no install step, runs anywhere Python 3.10+ is available.
 
 | Prompt | Purpose |
 |--------|---------|
+| `00-verification-core.md` | Canonical verification tags + verifier step (shared by all prompts) |
 | `01-architecture-overview.md` | System components & structure (with framework detection) |
 | `01a-overlay-model-systems.md` | Additional detection for ML/AI model systems |
 | `02-code-flows.md` | Execution path tracing |
@@ -93,21 +94,22 @@ Pure Python stdlib — no install step, runs anywhere Python 3.10+ is available.
 
 ## Framework-Specific Examples
 
-Each framework has its own mini reference app and good/bad documentation examples:
+Each framework has its own mini reference app (or vendored source) and good/bad documentation examples:
 
-| Framework | Mini App | Description |
-|-----------|----------|-------------|
-| Laravel | `examples/laravel/slotbooker/` | Booking system with MVC, events, services |
+| Framework | Source | Description |
+|-----------|--------|-------------|
+| Laravel | `examples/laravel/slotbooker/` | Booking system with MVC, events, services (+ code-flow example pair) |
 | FastAPI | `examples/fastapi/tasktracker/` | Task management API with repositories, Pydantic |
-| React | `examples/react/` | *(coming soon)* |
-| Vue | `examples/vue/` | *(coming soon)* |
-| Livewire | `examples/livewire/` | *(coming soon)* |
-| Flask | `examples/flask/` | *(coming soon)* |
+| React | `examples/react/expense-tracker/` | SPA with hooks, routing |
+| Next.js | `examples/nextjs/linkboard/` | App Router: server/client components, API routes |
+| Vue | `examples/vue/kanban-board/` | Pinia store, optimistic updates |
+| Livewire | `examples/livewire/approval-flow/` | Laravel + Livewire components |
+| Model-centric (ML/AI) | `examples/model-systems/whisper/` | Vendored openai/whisper source — pairs with the `01a` overlay |
 
-Each framework folder contains:
-- A mini reference app demonstrating that framework's patterns
-- `good-architecture-doc-example.md` - Properly verified documentation
-- `bad-architecture-doc-example.md` - Common hallucination patterns to avoid
+Each folder contains:
+- The mini app / vendored source the docs cite
+- `good-architecture-doc-example.md` - Properly verified documentation (**must pass `verify.py`** — enforced by `scripts/verify-examples.sh` in CI)
+- `bad-architecture-doc-example.md` - Common hallucination patterns, annotated with ❌ callouts explaining each failure
 
 ### Package/Library Examples
 
@@ -126,41 +128,39 @@ Package examples are in `examples/packages/{package}/` with the same good/bad do
 ```
 agent-system-mapper/
 ├── prompts/                     # AI agent prompts (what gets installed)
+│   ├── 00-verification-core.md       # Canonical tags + verifier step (shared)
 │   ├── 01-architecture-overview.md   # With framework detection
 │   ├── 01a-overlay-model-systems.md  # ML/AI model detection overlay
 │   ├── 02-code-flows.md
 │   ├── 02a-recommend-code-flows.md   # Analyze & recommend flows
 │   ├── 03-data-models.md
 │   ├── 04-diagrams.md
-│   └── 05-test-surface.md            # Test candidates from flows
-├── examples/                    # Framework-specific examples
-│   ├── laravel/
-│   │   ├── slotbooker/         # Laravel mini app
-│   │   ├── good-architecture-doc-example.md
-│   │   └── bad-architecture-doc-example.md
-│   ├── fastapi/
-│   │   ├── tasktracker/        # FastAPI mini app
-│   │   ├── good-architecture-doc-example.md
-│   │   └── bad-architecture-doc-example.md
-│   ├── react/                   # (coming soon)
-│   ├── vue/                     # (coming soon)
-│   ├── livewire/                # (coming soon)
-│   ├── flask/                   # (coming soon)
-│   ├── packages/                # Library/package examples
-│   │   └── requests/            # Python HTTP client
-│   └── test-surface/            # Test surface examples (framework-agnostic)
-│       ├── good-test-surface-example.md
-│       └── bad-test-surface-example.md
-├── guides/                      # Methodology guides
-│   └── 01-architecture-overview.md
+│   ├── 05-test-surface.md            # Test candidates from flows
+│   └── lsp/                          # LSP-optimized variants
+├── examples/                    # Every good example must pass verify.py (CI-enforced)
+│   ├── laravel/                 # slotbooker mini app + architecture AND code-flow pairs
+│   ├── fastapi/                 # tasktracker mini app + pair
+│   ├── react/                   # expense-tracker mini app + pair
+│   ├── nextjs/                  # linkboard mini app (App Router) + pair
+│   ├── vue/                     # kanban-board mini app + pair
+│   ├── livewire/                # approval-flow mini app + pair
+│   ├── model-systems/           # vendored openai/whisper + pair (01a overlay)
+│   ├── packages/
+│   │   └── requests/            # vendored requests source + pair
+│   ├── verifier/                # self-verifying example (documents verify.py)
+│   └── test-surface/            # test surface pair (cites slotbooker)
+├── skills/                      # Claude Code slash commands (/map-arch, /map-verify, ...)
+├── scripts/
+│   └── verify-examples.sh       # CI guard: every good example must PASS
+├── verify.py                    # Two-phase doc verifier
 └── install.sh                   # Installation script
 ```
 
 ---
 
 ## Getting Started (Contributors)
 
-1. Read the guides in `guides/` to understand the methodology
+1. Read the prompts in `prompts/` to understand the methodology (`guides/` is superseded)
 2. Examine mini apps in `examples/{framework}/` as reference implementations
 3. Review good vs bad examples to understand hallucination patterns
 4. Test prompts against mini apps to validate changes
@@ -176,8 +176,10 @@ The architecture prompt auto-detects frameworks using these patterns:
 | Laravel | `composer.json` with `laravel/framework` |
 | FastAPI | `requirements.txt` with `fastapi` |
 | React | `package.json` with `react` |
+| Next.js | `package.json` with `next` |
 | Vue | `package.json` with `vue` |
 | Livewire | Laravel + `livewire/livewire` in `composer.json` |
-| Flask | `requirements.txt` with `flask` |
+| Model-centric (ML/AI) | Weights files, `torch`/`transformers` deps — loads the `01a` overlay |
 
-If your framework isn't supported yet, use Laravel examples as a baseline.
+If your framework isn't supported yet, use the packages/requests examples as a
+generic baseline (or Laravel for web frameworks) and adapt terminology.

SKILLS.md

@@ -38,9 +38,11 @@ curl -sL "https://raw.githubusercontent.com/peak-flow/agent-system-mapper/master
 | `/map-flows [name]` | Document a specific code flow | Architecture doc |
 | `/map-flows-lsp [name]` | Code flow (LSP, 60% fewer tokens) | Architecture doc + LSP |
 | `/map-recommend` | Recommend which flows to document | Architecture doc |
+| `/map-recommend-lsp` | Flow recommendations (LSP-verified entry points + complexity) | Architecture doc + LSP |
 | `/map-data` | Document data models and schema | Prompts installed |
 | `/map-diagrams` | Generate Mermaid diagrams | At least one doc exists |
 | `/map-tests` | Derive test candidates from flows | Code flow doc |
+| `/map-verify [doc]` | Verify citations + quoted code; a doc is done only at PASS | Any generated doc |
 
 ---
 
@@ -53,17 +55,22 @@ The recommended workflow is:
          ↓
 2. /map-arch             → Document architecture (or /map-arch-lsp)
          ↓
-3. /map-recommend        → Get prioritized list of flows to document
+3. /map-verify           → Verify the doc (citations + quoted code); fix until PASS
          ↓
-4. /map-flows [name]     → Document each recommended flow (or /map-flows-lsp)
+4. /map-recommend        → Get prioritized list of flows to document
          ↓
-5. /map-data             → Document data models
+5. /map-flows [name]     → Document each recommended flow (or /map-flows-lsp)
          ↓
-6. /map-diagrams         → Generate visual diagrams
+6. /map-data             → Document data models
          ↓
-7. /map-tests            → Derive test candidates from flows
+7. /map-diagrams         → Generate visual diagrams
+         ↓
+8. /map-tests            → Derive test candidates from flows
 ```
 
+Run `/map-verify` after every doc-producing step (arch, flows, data, tests) —
+a doc is only "done" when `verify.py` exits 0.
+
 ---
 
 ## Skill Details
@@ -249,7 +256,7 @@ Derives test candidates from documented code flows.
 
 | Aspect | Standard (`/map-arch`) | LSP (`/map-arch-lsp`) |
 |--------|------------------------|----------------------|
-| Token usage | 15-26k | 7-12k |
+| Token usage | 8-12k (whole pipeline: 15-26k) | 4-6k (whole pipeline: 7-12k) |
 | Requirements | None | LSP server |
 | Best for | All languages | TypeScript, Python, PHP |
 | Tradeoff | Works everywhere | 50% fewer tokens |

examples/fastapi/bad-architecture-doc-example.md

@@ -1,9 +1,13 @@
 # TaskTracker Architecture Overview
 
+> ⚠️ **BAD EXAMPLE — DO NOT IMITATE.** This document demonstrates hallucination patterns. Each ❌ callout explains a failure. See good-architecture-doc-example.md for the correct approach.
+
 ## What This System Does
 
 TaskTracker is a comprehensive project management API built with FastAPI. It allows users to create projects, manage tasks, assign work to team members, and track progress with notifications.
 
+> **❌ PROBLEMS:** Pure uncited prose. No metadata block (commit, path, date), no verification summary, and not a single verification tag in the entire document. "Comprehensive" is marketing language, and "track progress with notifications" oversells reality — the only notification mechanism is a single outbound webhook (`app/services/notification_service.py:43-59`). A reader has no way to check any of this.
+
 ## Components
 
 ### API Layer
@@ -12,22 +16,30 @@ The system uses FastAPI routers to handle HTTP requests. Each resource has its o
 - Projects router manages project lifecycle
 - Tasks router handles task management with status updates
 
+> **❌ PROBLEMS:** This is the trap of *plausible* hallucination — these routers happen to exist (`app/api/users.py:12`, `app/api/projects.py:13`, `app/api/tasks.py:13`), but nothing here is cited, so the reader cannot tell this section apart from the fabricated ones below. Uncited-but-true is indistinguishable from uncited-and-false.
+
 ### Database Layer
 Uses SQLAlchemy ORM with async support for high-performance database operations. The models are well-structured with proper relationships:
 - User has many Projects and Tasks
 - Project has many Tasks
 - Task belongs to Project and User
 
+> **❌ PROBLEMS:** "Async support" is fabricated. The engine is created with the synchronous `create_engine` (`app/core/database.py:11-14`) and a plain `sessionmaker` (`app/core/database.py:16`); every route handler is a sync `def`, not `async def` (e.g. `app/api/tasks.py:17`). "High-performance" is unfounded editorializing — the code itself flags "No connection pooling configured" (`app/core/database.py:10`). The relationship bullets are roughly right (`app/models/user.py:22-23`) but carry no citations, so they add no verifiable information.
+
 ### Service Layer
 Business logic is handled by services:
 - TaskService handles task creation with notifications
 - ProjectService handles project operations
 - UserService manages user authentication
 - NotificationService sends emails and push notifications
 
+> **❌ PROBLEMS:** Half of this service roster is invented by naming symmetry. Only two services exist: `TaskService` (`app/services/task_service.py:14`) and `NotificationService` (`app/services/notification_service.py:13`). There is no `ProjectService` and no `UserService` — `app/services/` contains exactly `task_service.py`, `notification_service.py`, and `__init__.py`. "UserService manages user authentication" is doubly false: the class doesn't exist and neither does authentication. And `NotificationService` sends neither emails nor push notifications — it POSTs a JSON webhook via httpx (`app/services/notification_service.py:43-59`).
+
 ### Authentication
 The API uses JWT authentication with refresh tokens. Users authenticate via the /auth/login endpoint and receive access tokens.
 
+> **❌ PROBLEMS:** This entire section is fabricated. Searches for "jwt", "token", "login", and "auth" in `app/` and `main.py` return nothing. The only mounted routers are `/users`, `/projects`, and `/tasks` (`main.py:19-21`) plus `GET /health` (`main.py:24-25`) — there is no `/auth/login` endpoint and every endpoint is completely open. A good doc states this as a `[NOT_FOUND]` with the search terms; this doc invents the opposite.
+
 ## Data Flow
 
 1. Request comes in through FastAPI router
@@ -37,20 +49,26 @@ The API uses JWT authentication with refresh tokens. Users authenticate via the
 5. Repository layer handles database operations
 6. Response is serialized via Pydantic models
 
+> **❌ PROBLEMS:** Step-by-step execution tracing is a banned pattern in an architecture overview — prompt 01's Section 3 rules say "MUST NOT trace step-by-step execution"; detailed traces belong in the code-flows document. An architecture doc describes surfaces and what moves in tables (see Section 3 of the good example). This numbered walkthrough is also generic FastAPI boilerplate that would "document" any FastAPI app equally well, and it silently assumes every request goes through a service layer — in reality only the task routes use `TaskService` (`app/api/tasks.py:105`, `app/api/tasks.py:125`); user and project routes call repositories directly (`app/api/users.py:18`, `app/api/projects.py:19`).
+
 ## External Integrations
 
 - **Email Service**: Sends transactional emails via SendGrid
 - **Push Notifications**: Uses Firebase Cloud Messaging
 - **Webhook System**: Notifies external services of task events
 - **Redis Cache**: Caches frequently accessed data
 
+> **❌ PROBLEMS:** Three of these four integrations do not exist. Searches for "sendgrid", "smtp", "firebase", "redis", and "cache" in `app/` return nothing. The only real integration is the webhook (`app/services/notification_service.py:43-59`), configured by `NOTIFICATION_WEBHOOK_URL` and `NOTIFICATION_ENABLED` (`app/core/config.py:17-18`). One true bullet buried in three hallucinated ones is worse than useless — the reader cannot tell which is which.
+
 ## Key Patterns
 
 - Repository pattern for data access
 - Dependency injection via FastAPI's Depends
 - Async/await for non-blocking operations
 - Pydantic models for validation
 
+> **❌ PROBLEMS:** "Async/await for non-blocking operations" is false — there is not a single `async def` in `app/` or `main.py`; the notification path even uses a blocking `httpx.Client` (`app/services/notification_service.py:54`). The other three bullets are real (`app/repositories/task_repository.py:11`, `app/api/users.py:16`, `app/schemas/task.py:10`) but uncited, repeating the pattern of mixing verifiable truth and fabrication with no way to distinguish them.
+
 ## Database Schema
 
 | Table | Description |
@@ -60,3 +78,21 @@ The API uses JWT authentication with refresh tokens. Users authenticate via the
 | tasks | Tasks within projects |
 | notifications | Notification queue |
 | audit_log | Tracks all changes |
+
+> **❌ PROBLEMS:** Two of five tables are invented. Only three models declare `__tablename__`: users (`app/models/user.py:14`), projects (`app/models/project.py:22`), and tasks (`app/models/task.py:30`). There is no `notifications` table and no `audit_log` table — `app/models/` contains only `user.py`, `project.py`, `task.py`, and `__init__.py`. The users row is also wrong in detail: the User model has no password column, only id, email, name, and created_at (`app/models/user.py:16-19`) — consistent with the fact that no authentication exists.
+
+---
+
+## Why This Example is BAD
+
+Each numbered item pairs the false claim with the verifiable reality in `examples/fastapi/tasktracker/`:
+
+1. **"JWT authentication with refresh tokens" and a `/auth/login` endpoint** → No authentication of any kind exists. The only mounted routers are `/users`, `/projects`, `/tasks` (`main.py:19-21`) plus `GET /health` (`main.py:24-25`); searches for "jwt", "token", "login", "auth" in `app/` return nothing.
+2. **"SQLAlchemy ORM with async support"** → The database layer is synchronous: `create_engine` (`app/core/database.py:11-14`), `sessionmaker` (`app/core/database.py:16`), and sync `def` handlers throughout (e.g. `app/api/tasks.py:17`).
+3. **Service roster of TaskService, ProjectService, UserService, NotificationService** → Only `TaskService` (`app/services/task_service.py:14`) and `NotificationService` (`app/services/notification_service.py:13`) exist; `ProjectService` and `UserService` are invented.
+4. **"Sends transactional emails via SendGrid" and "Firebase Cloud Messaging" push** → `NotificationService` only POSTs a JSON webhook with httpx (`app/services/notification_service.py:43-59`); no email or push code exists anywhere.
+5. **"Redis Cache: Caches frequently accessed data"** → No caching layer; searches for "redis" and "cache" in `app/` return nothing.
+6. **users table with "email and password"** → The User model has no password column: id, email, name, created_at only (`app/models/user.py:16-19`).
+7. **`notifications` and `audit_log` tables** → Do not exist; the only tables are users (`app/models/user.py:14`), projects (`app/models/project.py:22`), and tasks (`app/models/task.py:30`).
+8. **Step-by-step "Data Flow" section** → A banned pattern in the architecture overview (prompt 01 Section 3: "MUST NOT trace step-by-step execution"); detailed tracing belongs in the code-flows document, and Section 3 of the good example shows the table-based alternative.
+9. **Zero verification tags** → Not one `[VERIFIED: path:line]` or `[NOT_FOUND]` in the whole document, so nothing is checkable — `verify.py` finds no citations to resolve, and every claim (true or false) reads identically. Cite or admit; there is no middle ground.