pi-skill-search 0.1.0

package/skills/using-vetc/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: using-vetc
+description: VETC bootstrap — auto-detect and invoke VETC skills based on task context. Always active at session start.
+---
+
+# Using VETC Dev Kit
+
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill.
+</SUBAGENT-STOP>
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 10% chance a VETC skill might apply to what you are doing, invoke it via Skill tool. VETC skills contain domain-specific patterns, PASS/FAIL code examples, and VETC conventions that prevent bugs.
+
+IF A VETC SKILL APPLIES TO YOUR TASK, YOU MUST USE IT.
+</EXTREMELY-IMPORTANT>
+
+## Instruction Priority
+
+1. **User's explicit instructions** (CLAUDE.md, AGENTS.md, direct requests) — highest
+2. **VETC skills** — override default behavior where they conflict
+3. **Default system prompt** — lowest
+
+## How to Access VETC Skills
+
+Use the `Skill` tool. When invoked, skill content loads directly — follow it.
+
+## Skill Activation Guide
+
+| User Intent | Skill to Invoke |
+|-------------|----------------|
+| New feature, any kind | `vetc-sdlc` (SDLC router) |
+| Requirement unclear/mo ho | `vetc-deep-interview` |
+| Quick spec from requirement | `vetc-spec-driven` |
+| Co spec, can plan | `vetc-ralplan` or `vetc-plan` |
+| Co approved plan, implement | `vetc-ralph` |
+| Java/Spring Boot code | `vetc-java-patterns` |
+| React/TypeScript code | `vetc-frontend-patterns` |
+| Write tests | `vetc-tdd` |
+| Review code | `vetc-review` |
+| Security review | `vetc-security` |
+| Debug bug/error | `vetc-systematic-debugging` |
+
+## The Rule
+
+**Invoke relevant VETC skills BEFORE any response or action.** Even 10% chance = invoke to check. If invoked skill doesn't apply, skip it.
+
+## Decision Flow
+
+```
+User message → Check VETC skills? → Yes → Invoke Skill → Follow skill → Respond
+                                → No → Respond normally
+```
+
+## Red Flags — Rationalization Prevention
+
+| Thought | Reality |
+|---------|---------|
+| "This is too simple to need a skill" | Simple things breed complex bugs. Check skills. |
+| "I know what to do" | Skills evolve. Invoke current version. |
+| "Let me just code first" | Skill check comes BEFORE action. |
+| "The skill is overkill" | Prevention beats debugging. Use it. |
+| "Just a quick question" | Questions are tasks. Check for skills. |
+| "I remember this skill" | Skills get updated. Read current version. |
+| "This doesn't count as a task" | Any action = task. Check for skills. |
+| "I'll do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "The user didn't ask for a skill" | Skills activate PROACTIVELY based on context, not just on request. |
+
+## Skill Priority
+
+When multiple skills could apply:
+
+1. **Process skills first** (sdlc, debugging, spec-driven, deep-interview) — determine HOW to approach
+2. **Planning skills second** (ralplan, planner) — create the plan
+3. **Implementation skills third** (java-patterns, frontend-patterns, tdd) — guide execution
+4. **Verification skills last** (verify, security, review) — validate results
+
+## SDLC Routing
+
+Most tasks start with `vetc-sdlc` which routes to the correct path:
+
+- **Path A** — Full BA Pipeline (co tai lieu BA)
+- **Path B** — Quick Path (requirement ro, no BA doc)
+- **Path C** — Consensus Planning (need clarify + plan review)
+
+## User Instructions Override
+
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip skills. Skills guide the HOW.
+
+
+

package/skills/vaex/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: vaex
+description: Use this skill for processing and analyzing large tabular datasets (billions of rows) that exceed available RAM. Vaex excels at out-of-core DataFrame operations, lazy evaluation, fast aggregations, efficient visualization of big data, and machine learning on large datasets. Apply when users need to work with large CSV/HDF5/Arrow/Parquet files, perform fast statistics on massive datasets, create visualizations of big data, or build ML pipelines that do not fit in memory.
+---
+
+# Vaex
+
+## Overview
+
+Vaex is a high-performance Python library designed for lazy, out-of-core DataFrames to process and visualize tabular datasets that are too large to fit into RAM. Vaex can process over a billion rows per second, enabling interactive data exploration and analysis on datasets with billions of rows.
+
+## When to Use This Skill
+
+Use Vaex when:
+- Processing tabular datasets larger than available RAM (gigabytes to terabytes)
+- Performing fast statistical aggregations on massive datasets
+- Creating visualizations and heatmaps of large datasets
+- Building machine learning pipelines on big data
+- Converting between data formats (CSV, HDF5, Arrow, Parquet)
+- Needing lazy evaluation and virtual columns to avoid memory overhead
+- Working with astronomical data, financial time series, or other large-scale scientific datasets
+
+## Core Capabilities
+
+Vaex provides six primary capability areas, each documented in detail in the references directory:
+
+### 1. DataFrames and Data Loading
+
+Load and create Vaex DataFrames from various sources including files (HDF5, CSV, Arrow, Parquet), pandas DataFrames, NumPy arrays, and dictionaries. Reference `(see docs)` for:
+- Opening large files efficiently
+- Converting from pandas/NumPy/Arrow
+- Working with example datasets
+- Understanding DataFrame structure
+
+### 2. Data Processing and Manipulation
+
+Perform filtering, create virtual columns, use expressions, and aggregate data without loading everything into memory. Reference `(see docs)` for:
+- Filtering and selections
+- Virtual columns and expressions
+- Groupby operations and aggregations
+- String operations and datetime handling
+- Working with missing data
+
+### 3. Performance and Optimization
+
+Leverage Vaex's lazy evaluation, caching strategies, and memory-efficient operations. Reference `(see docs)` for:
+- Understanding lazy evaluation
+- Using `delay=True` for batching operations
+- Materializing columns when needed
+- Caching strategies
+- Asynchronous operations
+
+### 4. Data Visualization
+
+Create interactive visualizations of large datasets including heatmaps, histograms, and scatter plots. Reference `(see docs)` for:
+- Creating 1D and 2D plots
+- Heatmap visualizations
+- Working with selections
+- Customizing plots and subplots
+
+### 5. Machine Learning Integration
+
+Build ML pipelines with transformers, encoders, and integration with scikit-learn, XGBoost, and other frameworks. Reference `(see docs)` for:
+- Feature scaling and encoding
+- PCA and dimensionality reduction
+- K-means clustering
+- Integration with scikit-learn/XGBoost/CatBoost
+- Model serialization and deployment
+
+### 6. I/O Operations
+
+Efficiently read and write data in various formats with optimal performance. Reference `(see docs)` for:
+- File format recommendations
+- Export strategies
+- Working with Apache Arrow
+- CSV handling for large files
+- Server and remote data access
+
+## Quick Start Pattern
+
+For most Vaex tasks, follow this pattern:
+
+```python
+import vaex
+
+# 1. Open or create DataFrame
+df = vaex.open('large_file.hdf5')  # or .csv, .arrow, .parquet
+# OR
+df = vaex.from_pandas(pandas_df)
+
+# 2. Explore the data
+print(df)  # Shows first/last rows and column info
+df.describe()  # Statistical summary
+
+# 3. Create virtual columns (no memory overhead)
+df['new_column'] = df.x ** 2 + df.y
+
+# 4. Filter with selections
+df_filtered = df[df.age > 25]
+
+# 5. Compute statistics (fast, lazy evaluation)
+mean_val = df.x.mean()
+stats = df.groupby('category').agg({'value': 'sum'})
+
+# 6. Visualize
+df.plot1d(df.x, limits=[0, 100])
+df.plot(df.x, df.y, limits='99.7%')
+
+# 7. Export if needed
+df.export_hdf5('output.hdf5')
+```

package/skills/venue-templates/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: venue-templates
+description: Access comprehensive LaTeX templates, formatting requirements, and submission guidelines for major scientific publication venues (Nature, Science, PLOS, IEEE, ACM), academic conferences (NeurIPS, ICML, CVPR, CHI), research posters, and grant proposals (NSF, NIH, DOE, DARPA). This skill should be used when preparing manuscripts for journal submission, conference papers, research posters, or grant proposals and need venue-specific formatting requirements and templates.
+---
+
+# Venue Templates
+
+## Overview
+
+Access comprehensive LaTeX templates, formatting requirements, and submission guidelines for major scientific publication venues, academic conferences, research posters, and grant proposals. This skill provides ready-to-use templates and detailed specifications for successful academic submissions across disciplines.
+
+Use this skill when preparing manuscripts for journal submission, conference papers, research posters, or grant proposals and need venue-specific formatting requirements and templates.
+
+## When to Use This Skill
+
+This skill should be used when:
+- Preparing a manuscript for submission to a specific journal (Nature, Science, PLOS, IEEE, etc.)
+- Writing a conference paper with specific formatting requirements (NeurIPS, ICML, CHI, etc.)
+- Creating an academic research poster for conferences
+- Drafting grant proposals for federal agencies (NSF, NIH, DOE, DARPA) or private foundations
+- Checking formatting requirements and page limits for target venues
+- Customizing templates with author information and project details
+- Verifying document compliance with venue specifications
+
+## Visual Enhancement with Scientific Schematics
+
+**When creating documents with this skill, always consider adding scientific diagrams and schematics to enhance visual communication.**
+
+If your document does not already contain schematics or diagrams:
+- Use the **scientific-schematics** skill to generate AI-powered publication-quality diagrams
+- Simply describe your desired diagram in natural language
+- Nano Banana Pro will automatically generate, review, and refine the schematic
+
+**For new documents:** Scientific schematics should be generated by default to visually represent key concepts, workflows, architectures, or relationships described in the text.
+
+**How to generate schematics:**
+```bash
+python scripts/generate_schematic.py "your diagram description" -o figures/output.png
+```
+
+## Core Capabilities
+
+### 1. Journal Article Templates
+
+Access LaTeX templates and formatting guidelines for 50+ major scientific journals across disciplines:
+
+**Nature Portfolio**:
+- Nature, Nature Methods, Nature Biotechnology, Nature Machine Intelligence
+- Nature Communications, Nature Protocols
+- Scientific Reports
+
+**Science Family**:
+- Science, Science Advances, Science Translational Medicine
+- Science Immunology, Science Robotics
+
+**PLOS (Public Library of Science)**:
+- PLOS ONE, PLOS Biology, PLOS Computational Biology
+
+### 2. Conference Paper Templates
+
+Conference-specific templates with proper formatting for major academic conferences:
+
+**Machine Learning & AI**:
+- NeurIPS (Neural Information Processing Systems)
+- ICML (International Conference on Machine Learning)
+- ICLR (International Conference on Learning Representations)
+- CVPR (Computer Vision and Pattern Recognition)
+- AAAI (Association for the Advancement of Artificial Intelligence)
+
+**Computer Science**:
+- ACM CHI (Human-Computer Interaction)
+- SIGKDD (Knowledge Discovery and Data Mining)
+- EMNLP (Empirical Methods in Natural Language Processing)
+
+### 3. Research Poster Templates
+
+Academic poster templates for conference presentations:
+
+**Standard Formats**:
+- A0 (841 × 1189 mm / 33.1 × 46.8 in)
+- A1 (594 × 841 mm / 23.4 × 33.1 in)
+- 36" × 48" (914 × 1219 mm) - Common US size
+- 42" × 56" (1067 × 1422 mm)
+- 48" × 36" (landscape orientation)
+
+**Template Packages**:
+- **beamerposter**: Classic academic poster template
+- **tikzposter**: Modern, colorful poster design
+- **baposter**: Structured multi-column layout
+
+### 4. Grant Proposal Templates
+
+Templates and formatting requirements for major funding agencies:
+
+**NSF (National Science Foundation)**:
+- Full proposal template (15-page project description)
+- Project Summary (1 page: Overview, Intellectual Merit, Broader Impacts)
+- Budget and budget justification
+- Biographical sketch (3-page limit)
+- Facilities, Equipment, and Other Resources
+- Data Management Plan
+
+**NIH (National Institutes of Health)**:
+- R01 Research Grant (multi-year)
+- R21 Exploratory/Developmental Grant
+
+## Workflow: Finding and Using Templates
+
+### Step 1: Identify Target Venue
+
+Determine the specific publication venue, conference, or funding agency:
+
+

package/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```

package/skills/verification-before-done/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: verification-before-done
+description: Use when about to claim work is complete, fixed, passing, reviewed, committed, or ready to hand off.
+---
+
+
+# verification-before-done
+
+Core principle: evidence before claims. A worker report, green-looking log, or previous run is not fresh verification.
+
+Distilled from detailed reads of agent-skill patterns for verification-before-completion, TDD, review reception, and QA workflows.
+
+## Gate Function
+
+Before any completion claim:
+
+1. Identify the command or inspection that proves the claim.
+2. Run the full command fresh, or explicitly state why a command cannot be run.
+3. Read the output, including exit code and failure counts.
+4. Compare the output to the claim.
+5. Report the claim only with the evidence.
+
+## Claim-to-Evidence Table
+
+| Claim | Requires | Not sufficient |
+|---|---|---|
+| Tests pass | Fresh test output with zero failures | Prior run, "should pass" |
+| Typecheck passes | Typecheck command exit 0 | Lint or targeted tests only |
+| Bug fixed | Original symptom/regression test passes | Code changed |
+| Requirements met | Checklist against request/plan | Generic test success |
+| Agent completed | Worker output plus artifact/diff/state inspection | Worker says DONE |
+| Safe to commit | Relevant checks pass and status reviewed | Partial local confidence |
+
+## Verification Ladder
+
+Choose the smallest reliable gate, then escalate when risk requires it:
+
+1. Read-only inspection for plans/reviews.
+2. Targeted unit test for touched behavior.
+3. Typecheck for TypeScript/schema/API changes.
+4. Integration test for runtime, subprocess, state, filesystem, UI, config, or session behavior.
+5. Full suite before commit/release or broad changes.
+6. Real Pi smoke only when safe and needed.
+
+## Done Report
+
+Include:
+
+- changed files or read-only status;
+- commands run and pass/fail result;
+- artifacts, run IDs, logs, or state paths inspected;
+- behavior actually verified;
+- skipped checks and why;
+- risks and rollback notes.
+
+## Required Final Evidence
+
+Before finalizing any work, report:
+
+- **changed files**: list of files modified (or `none` for read-only work)
+- **tests/checks run**: command and pass/fail result for each
+- **artifacts**: run IDs, log paths, or state files inspected
+- **risks and rollback notes**: any known risks, how to undo the changes
+
+## Red Flags
+
+Stop before saying done if you are using words like "should", "probably", "looks", "seems", "I think", or if you are trusting an agent report without checking evidence.
+

package/skills/verify/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: verify
+description: Verify that a change really works before you claim completion
+---
+
+# Verify
+
+Use this skill when the user wants confidence that a feature, fix, or refactor actually works.
+
+## Goal
+Turn vague “it should work” claims into concrete evidence.
+
+## Workflow
+1. Identify the exact behavior that must be proven.
+2. Prefer existing tests first.
+3. If coverage is missing, run the narrowest direct verification commands available.
+4. If direct automation is not enough, describe the manual validation steps and gather concrete observable evidence.
+5. Report only what was actually verified.
+
+## Verification order
+1. Existing tests
+2. Typecheck / build
+3. Narrow direct command checks
+4. Manual or interactive validation
+
+## Rules
+- Do not say a change is complete without evidence.
+- If a check fails, include the failure clearly.
+- If no realistic verification path exists, say that explicitly instead of bluffing.
+- Prefer concise evidence summaries over noisy logs.
+
+
+

package/skills/version-bump/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: version-bump
+description: Automated semantic versioning and release workflow for Claude Code plugins. Handles version increments across package.json, marketplace.json, plugin.json manifests, npm publishing (so `npx claude-mem@X.Y.Z` resolves), build verification, git tagging, GitHub releases, and changelog generation.
+---
+
+# Version Bump & Release Workflow
+
+**IMPORTANT:** Plan and write detailed release notes before starting.
+
+**CRITICAL:** Commit EVERYTHING (including build artifacts). At the end of this workflow, NOTHING should be left uncommitted or unpushed. Run `git status` at the end to verify.
+
+## Preparation
+
+1.  **Analyze**: Determine if the change is **PATCH** (bug fixes), **MINOR** (features), or **MAJOR** (breaking).
+2.  **Environment**: Identify repository owner/name from `git remote -v`.
+3.  **Paths — every file that carries the version string**:
+    - `package.json` — **the npm/npx-published version** (`npx claude-mem@X.Y.Z` resolves from this)
+    - `plugin/package.json` — bundled plugin runtime deps
+    - `.claude-plugin/marketplace.json` — version inside `plugins[0].version`
+    - `.claude-plugin/plugin.json` — top-level Claude-plugin manifest
+    - `plugin/.claude-plugin/plugin.json` — bundled Claude-plugin manifest
+    - `.codex-plugin/plugin.json` — Codex-plugin manifest
+    - `openclaw/openclaw.plugin.json` — OpenClaw plugin manifest
+
+    Verify coverage before editing: `git grep -l "\"version\": \"\""` should list all seven. If a new manifest has been added since this doc was last updated, update this list.
+
+## Workflow
+
+1.  **Update**: Increment the version string in every path above. Do NOT touch `CHANGELOG.md` — it's regenerated.
+2.  **Verify**: `git grep -n "\"version\": \"\""` — confirm all seven files match. `git grep -n "\"version\": \"\""` — should return zero hits.
+3.  **Build and sync**: `npm run build-and-sync` to regenerate artifacts, sync the local marketplace copy, restart the worker, and clear the queue. Do not use plain `npm run build` for release validation because it can leave the local marketplace/worker out of sync.
+4.  **Commit**: `git add -A && git commit -m "chore: bump version to X.Y.Z"`.
+5.  **Tag**: `git tag -a vX.Y.Z -m "Version X.Y.Z"`.
+6.  **Push**: `git push origin main && git push origin vX.Y.Z`.
+7.  **Publish to npm** (this is what makes `npx claude-mem@X.Y.Z` work):
+    ```bash
+    npm publish
+    ```
+    The `prepublishOnly` script re-runs the package build automatically. After publish, run `npm run build-and-sync` again if the publish build touched local artifacts. Confirm publish succeeded:
+    ```bash
+    npm view claude-mem@X.Y.Z version   # should print X.Y.Z
+
+## Checklist
+
+- [ ] All seven config files have matching versions
+- [ ] `git grep` for old version returns zero hits
+- [ ] `npm run build-and-sync` succeeded
+- [ ] Git tag created and pushed
+- [ ] **`npm publish` succeeded and `npm view claude-mem@X.Y.Z version` confirms it** (so `npx claude-mem@X.Y.Z` resolves)
+- [ ] GitHub release created with notes
+- [ ] `CHANGELOG.md` updated and pushed
+- [ ] Discord notification run from `~/Scripts/claude-mem/`
+- [ ] `git status` shows clean tree
+```

package/skills/vetc-analyze-ba/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: vetc-analyze-ba
+description: PROACTIVELY activate khi đã có raw-ba-requirements.md hoặc BA doc đã chuẩn hóa. 13-step gated pipeline từ BA Analysis → Spec → Design → API → Tasks → Code → Security → Test → Verify → Perf.
+---
+
+# VETC Analyze BA — 13-Step BA→Code Pipeline
+
+Nhận `raw-ba-requirements.md`, chuyển thành code production-ready theo 13 bước có gate review.
+
+## When to Activate
+
+- Đã có `specs/features/{feature}/raw-ba-requirements.md`
+- Muốn implement tính năng từ tài liệu BA theo quy trình đầy đủ
+- Dùng sau `vetc-thinking-pm` (đã chuẩn hóa BA input)
+
+## Do NOT Activate When
+
+- Chưa có BA document (dùng `vetc-thinking-pm` hoặc `vetc-deep-interview` trước)
+- Chỉ cần code review, không implement từ BA spec
+- Requirement đã crystal clear, không cần 13-step pipeline (dùng quick path)
+
+## Thứ tự dùng
+
+```
+vetc-analyze-codebase → vetc-thinking-pm → vetc-analyze-ba  ← skill này
+```
+
+## Pre-conditions
+
+- `specs/features/{feature}/raw-ba-requirements.md` phải tồn tại
+- `docs/architecture/codebase-spec.md` phải tồn tại (Phase 4 yêu cầu) — nếu chưa có → chạy `vetc-analyze-codebase` trước
+
+## Modes
+
+| Mode | Phases | Dùng khi |
+|------|--------|---------|
+| `--parse-only` | 1-2 | Chỉ phân tích + làm rõ |
+| `--design-only` | 1-5 | Phân tích đến API design, không code |
+| `--continue` | Tiếp từ chỗ dở | Mở session mới, tiếp tục |
+| (default) | 1-13 | Full pipeline |
+
+## Cấu trúc output
+
+specs/features/{feature}/
+├── 00-anti-hallucination.md  ← Tạo đầu tiên (Bước 0), update sau Phase 3
+├── 00-run-ledger.md          ← Timeline (tạo Phase 1, cập nhật mỗi phase)
+├── 00-local-memory-context.md← Mirror context + lessons-learned
+├── memory/                   ← Phase 3b — context snapshot
+│   └── {feature}.md
+├── raw-ba-requirements.md    ← INPUT
+├── 01-ba-analysis.md         ← Phase 1
+├── 02-clarify-questions.md   ← Phase 2
+├── 03-feature-spec.md        ← Phase 3 (SOURCE OF TRUTH)
+├── 04-technical-design.md    ← Phase 4
+├── 05-api-design.md          ← Phase 5
+
+## 13 Phases
+
+### Phase 1 — PARSE → `01-ba-analysis.md`
+Đọc `raw-ba-requirements.md`, tách: Requirements, Business Rules, Data, Edge Cases, NFRs, GAPs.
+
+**Auto-sizing sau Phase 1:**
+| Size | Endpoints | Tables mới | Mode |
+|------|-----------|-----------|------|
+| XS | 1 | 0 | Redirect → quick feature |
+| S | 2-3 | 0-1 | LITE |
+| M | 4-7 | 1-3 | STANDARD |
+| L/XL | 8+ | 3+ | FULL |
+
+⏸️ DỪNG → chờ user review + confirm size/mode.
+
+### Phase 2 — CLARIFY → `02-clarify-questions.md`
+Từ GAPs → danh sách câu hỏi cho BA (chức năng, nghiệp vụ, dữ liệu, edge cases) + assumptions.
+⏸️ DỪNG → chờ BA trả lời → update file → confirm.
+
+### Phase 3 — STRUCTURE → `03-feature-spec.md` (SOURCE OF TRUTH)
+Chuyển analysis + clarify → Feature Spec với:
+- User Stories, Requirements, Business Rules
+- API Contract sketch (VETC format)
+- Data Model (table, columns, indexes)
+- State Flow (nếu có)
+- Error Scenarios
+- Acceptance Criteria
+- Design Decisions & Constraints
+
+**Sau Phase 3 (BẮT BUỘC):** Cập nhật `00-anti-hallucination.md` + tạo `specs/features/{feature}/memory/{feature}.md` (context snapshot).
+
+⏸️ DỪNG → chờ review.
+
+### Phase 4 — DESIGN → `04-technical-design.md`
+**Gate bắt buộc:** phải có `docs/architecture/codebase-spec.md`.
+- Detect architecture từ codebase-spec (LAYERED / HEXAGONAL)
+- File changes: new files + modified files (với full path theo architecture)
+- DB migration SQL (Flyway format)
+- Sequence flow
+- Implementation order: DB → Entity → Repository → DTO → Service → Controller → Tests
+
+⏸️ DỪNG → chờ confirm.
+
+### Phase 5 — API DESIGN → `05-api-design.md` (VETC format)
+Thiết kế API theo chuẩn VETC (từ `../../shared/api-design.md`):
+- API Index table
+- Per-API: 15 fields + Headers + Query Params + Request/Response Body + Error Codes + curl example
+- Response format: `{ code, message, data, meta_data: { request_id, page, size, total, total_pages } }`
+- Error codes: `200`, `400xxx`, `401xxx`, `403xxx`, `404xxx`, `409xxx`, `500xxx`
+- PII fields: mask trong response
+
+⏸️ DỪNG → chờ confirm per-API.
+
+### Phase 6 — TASK BREAKDOWN → `06-task-breakdown.md`
+**⚠️ KHÔNG có file này → TUYỆT ĐỐI KHÔNG implement.**
+- Tách theo `04-technical-design.md`
+- Mỗi task: scope (files), boundary, rule check, dependency, risk & impact table
+
+⏸️ DỪNG → chờ review.
+
+