@ngockhoale/ukit 1.6.8 → 2.0.1

package/templates/.claude/agents/code-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: code-reviewer
-description: "Independent reviewer for handoff Phase 3. Use after executor reports STATUS: DONE on a handoff task. MUST run with a model different from the executor (configured in .ukit/storage/config.json → handoff.reviewer.model, default unic-smart). Produces a verdict: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL."
+description: "Independent reviewer for handoff Phase 3, and for spec/plan documents. For code (default): use after executor reports STATUS: DONE on a handoff task, MUST run with a model different from the executor (configured in .ukit/storage/config.json → handoff.reviewer.model, default unic-smart), produces a verdict: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL. For spec/plan documents (set REVIEW_TARGET_TYPE=spec or plan): reviews a docs/plans/*.md file for completeness/consistency/clarity/scope/YAGNI, produces Status: Approved | Issues Found."
 model: opus  # unic-smart
 color: yellow
 tools: ["Read", "Grep", "Glob", "Bash"]
@@ -10,7 +10,14 @@ You are the independent reviewer for UKit's handoff Quality Gate. Your model is
 
 **Do not invent issues. Do not rubber-stamp.** Every finding must point at a specific file + line + concrete failure mode.
 
-## Inputs you expect
+## REVIEW_TARGET_TYPE
+
+- `code` (default, if not specified) — reviewing a handoff task diff. Follow **Code Review** below, unchanged.
+- `spec` | `plan` — reviewing a document (e.g. `docs/plans/*.md`), no diff/task file/executor report involved. Skip straight to **Spec/Plan Review** at the end of this file instead.
+
+## Code Review (REVIEW_TARGET_TYPE=code)
+
+### Inputs you expect
 
 - Path to task file: `docs/AI_HANDOFF/tasks/TASK-xxx.md` (has Test Plan §4 + Verification Commands + Executor Report at bottom).
 - The executor's `STATUS: DONE` report with FILES_CHANGED + VERIFICATION block.
@@ -18,7 +25,7 @@ You are the independent reviewer for UKit's handoff Quality Gate. Your model is
 
 If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete handoff package".
 
-## Review order
+### Review order
 
 1. **Test Plan adherence** — Were all tests in §4 actually implemented? Run them yourself: `<task Verification Commands>`. Fresh PASS required, no trusting executor's output blindly.
 2. **Correctness** — Does the diff implement the requested behavior? Any obvious wrong assumptions, stale refs, missing cases?
@@ -27,14 +34,14 @@ If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete hand
 5. **Performance / scale** — Accidental N+1, repeated I/O, large scans inside hot paths.
 6. **Maintainability** — Duplicated logic, dead branches, misleading naming, drift between docs/tests/source.
 
-## Severity ladder
+### Severity ladder
 
 - **CRITICAL** — security hole, data loss risk, broken core behavior, test was faked (no real assertion), or verification command does NOT actually pass when you re-run it. Blocks handoff cứng.
 - **CHANGES-REQUESTED** — Important issues: missing edge-case test, regression risk in shared code, wrong abstraction at scope boundary. Executor must fix and re-submit.
 - **APPROVED-WITH-MINOR** — Minor naming / doc / style issues. Logged on task file but handoff allowed.
 - **APPROVED** — Clean.
 
-## Output (append to task file as `## Reviewer Verdict`)
+### Output (append to task file as `## Reviewer Verdict`)
 
 ```
 ## Reviewer Verdict
@@ -59,7 +66,7 @@ NOTES: [1-2 sentences for human reviewer if needed]
 
 After writing the verdict, update `docs/AI_HANDOFF/INDEX.md` row for this task: set Status = NEXT_STATUS_FOR_INDEX, set Reviewer = your model name.
 
-## Model isolation check (FIRST thing you do)
+### Model isolation check (FIRST thing you do)
 
 UKit cannot force any tool to use a specific model. The contract is enforced HERE, by you, via self-report comparison.
 
@@ -77,10 +84,47 @@ UKit cannot force any tool to use a specific model. The contract is enforced HER
 
 Same model is the most common silent failure. Do not skip this check.
 
-## Rules
+### Rules
 
 - **Always re-run** the task's Verification Commands. If they fail, VERDICT = CRITICAL regardless of executor claims.
 - If executor said `TEST_PLAN_FOLLOWED: N/A` without a real justification, downgrade to at minimum CHANGES-REQUESTED.
 - Never approve when test file has no real `expect`/`assert` - that is a fake test -> CRITICAL.
 - Keep the verdict block <= 30 lines. Findings are bullet points, not essays.
 - The same-model refusal above is non-negotiable: bypassing it defeats the entire Quality Gate.
+
+## Spec/Plan Review (REVIEW_TARGET_TYPE=spec|plan)
+
+### Inputs you expect
+
+- Path to the spec/plan document (e.g. `docs/plans/*.md`). No diff, no task file, no executor report — review the document itself.
+
+### Review order
+
+| Category | What to look for |
+|---|---|
+| Completeness | TODO/TBD/placeholders, incomplete sections |
+| Consistency | internal contradictions, conflicting requirements |
+| Clarity | requirements ambiguous enough to cause a wrong build |
+| Scope | focused enough for one plan, not silently covering multiple subsystems |
+| YAGNI | unrequested features, over-engineering |
+
+Only flag issues that would cause real problems during implementation planning. Approve unless there are serious gaps that would lead to a flawed plan.
+
+### Output
+
+```
+Status: Approved | Issues Found
+
+COMPLETENESS:
+  - <finding, or "none">
+CONSISTENCY:
+  - <finding, or "none">
+CLARITY:
+  - <finding, or "none">
+SCOPE:
+  - <finding, or "none">
+YAGNI:
+  - <finding, or "none">
+
+NOTES: [1-2 sentences if needed]
+```

package/templates/.claude/agents/handoff-planner.md

@@ -15,9 +15,21 @@ Use the strongest model available — planning with a weak model produces weak t
 - **Pre-read context** (if provided): compact summary of INDEX.md, ACTIVE.md, RULES.md, _TEMPLATE.md. Use it directly — do NOT re-read those files.
 - If no pre-read context → read the files yourself (fallback for direct invocation).
 
+## Scope Check (before Phase 1)
+
+Before refining the request into `PLAN.md`, check whether it describes multiple independent subsystems (e.g. "CRM + AI + billing + analytics + mobile app"). If yes, stop and output a decomposition table instead of planning the mega-spec:
+
+```
+Scope complexity: HIGH
+Detected systems: [...]
+Recommended decomposition: N modules — plan each as a separate PLAN.md
+```
+
+Wait for human confirmation before writing `PLAN.md`.
+
 ## Phase 1 — Write PLAN.md
 
-Write all 6 sections to `docs/AI_HANDOFF/PLAN.md`:
+Write all 7 sections to `docs/AI_HANDOFF/PLAN.md`:
 
 ```
 §1 Intent       — what problem, what success looks like
@@ -29,6 +41,9 @@ Write all 6 sections to `docs/AI_HANDOFF/PLAN.md`:
                   table: | Type | Test Name | Expected |
 §5 Verification — exact shell commands executor will run
 §6 Acceptance   — checklist of done criteria (prefer verifiable/command-based criteria)
+§7 Global Constraints — one line each: version floors, dependency limits, naming/copy
+                  rules, platform requirements. Every TASK-xxx.md inherits this section
+                  by reference — do not repeat these constraints inside each task.
 ```
 
 **§4 is non-negotiable.** No test plan = plan not ready.
@@ -42,6 +57,8 @@ PLANNER_MODEL: <your exact model ID — e.g. claude-opus-4-6>
 
 ## Phase 2 — Split into TASK-xxx.md
 
+**Right-sizing rule:** A task is the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate. Split only where a reviewer could meaningfully approve one task while rejecting its neighbor. Each task ends with an independently testable deliverable.
+
 Use `_TEMPLATE.md` structure (from pre-read context or file).
 
 **Every task MUST have all fields:**
@@ -87,5 +104,4 @@ Wave structure is NOT stored here — inferred from task `Dependencies` fields a
 
 - Do NOT implement. Job ends when all tasks are `ready` or `needs_breakdown`.
 - Undone tasks in INDEX.md → warn human: continue old cycle or start fresh?
-- Prefer smaller tasks. Each task = one executor session.
 - Cannot determine test cases → `needs_breakdown` + Discussion thread note.

package/templates/.claude/skills/canvas-design/SKILL.md

@@ -52,27 +52,9 @@ The philosophy must guide the next version to express ideas VISUALLY, not throug
 
 ### PHILOSOPHY EXAMPLES
 
-**"Concrete Poetry"**
-Philosophy: Communication through monumental form and bold geometry.
-Visual expression: Massive color blocks, sculptural typography (huge single words, tiny labels), Brutalist spatial divisions, Polish poster energy meets Le Corbusier. Ideas expressed through visual weight and spatial tension, not explanation. Text as rare, powerful gesture - never paragraphs, only essential words integrated into the visual architecture. Every element placed with the precision of a master craftsman.
+Five condensed reference examples ("Concrete Poetry", "Chromatic Language", "Analog Meditation", "Organic Systems", "Geometric Silence") showing the philosophy → visual-expression pattern are in [`philosophy-examples.md`](philosophy-examples.md).
 
-**"Chromatic Language"**
-Philosophy: Color as the primary information system.
-Visual expression: Geometric precision where color zones create meaning. Typography minimal - small sans-serif labels letting chromatic fields communicate. Think Josef Albers' interaction meets data visualization. Information encoded spatially and chromatically. Words only to anchor what color already shows. The result of painstaking chromatic calibration.
-
-**"Analog Meditation"**
-Philosophy: Quiet visual contemplation through texture and breathing room.
-Visual expression: Paper grain, ink bleeds, vast negative space. Photography and illustration dominate. Typography whispered (small, restrained, serving the visual). Japanese photobook aesthetic. Images breathe across pages. Text appears sparingly - short phrases, never explanatory blocks. Each composition balanced with the care of a meditation practice.
-
-**"Organic Systems"**
-Philosophy: Natural clustering and modular growth patterns.
-Visual expression: Rounded forms, organic arrangements, color from nature through architecture. Information shown through visual diagrams, spatial relationships, iconography. Text only for key labels floating in space. The composition tells the story through expert spatial orchestration.
-
-**"Geometric Silence"**
-Philosophy: Pure order and restraint.
-Visual expression: Grid-based precision, bold photography or stark graphics, dramatic negative space. Typography precise but minimal - small essential text, large quiet zones. Swiss formalism meets Brutalist material honesty. Structure communicates, not words. Every alignment the work of countless refinements.
-
-*These are condensed examples. The actual design philosophy should be 4-6 substantial paragraphs.*
+*The actual design philosophy should be 4-6 substantial paragraphs.*
 
 ### ESSENTIAL PRINCIPLES
 - **VISUAL PHILOSOPHY**: Create an aesthetic worldview to be expressed through design

package/templates/.claude/skills/canvas-design/philosophy-examples.md

@@ -0,0 +1,23 @@
+# Canvas Design Philosophy Examples
+
+Condensed reference examples showing the philosophy → visual-expression pattern described in `SKILL.md`. Use these to spark creativity, not as a fixed catalog — the actual design philosophy for a piece should be 4-6 substantial paragraphs.
+
+**"Concrete Poetry"**
+Philosophy: Communication through monumental form and bold geometry.
+Visual expression: Massive color blocks, sculptural typography (huge single words, tiny labels), Brutalist spatial divisions, Polish poster energy meets Le Corbusier. Ideas expressed through visual weight and spatial tension, not explanation. Text as rare, powerful gesture - never paragraphs, only essential words integrated into the visual architecture. Every element placed with the precision of a master craftsman.
+
+**"Chromatic Language"**
+Philosophy: Color as the primary information system.
+Visual expression: Geometric precision where color zones create meaning. Typography minimal - small sans-serif labels letting chromatic fields communicate. Think Josef Albers' interaction meets data visualization. Information encoded spatially and chromatically. Words only to anchor what color already shows. The result of painstaking chromatic calibration.
+
+**"Analog Meditation"**
+Philosophy: Quiet visual contemplation through texture and breathing room.
+Visual expression: Paper grain, ink bleeds, vast negative space. Photography and illustration dominate. Typography whispered (small, restrained, serving the visual). Japanese photobook aesthetic. Images breathe across pages. Text appears sparingly - short phrases, never explanatory blocks. Each composition balanced with the care of a meditation practice.
+
+**"Organic Systems"**
+Philosophy: Natural clustering and modular growth patterns.
+Visual expression: Rounded forms, organic arrangements, color from nature through architecture. Information shown through visual diagrams, spatial relationships, iconography. Text only for key labels floating in space. The composition tells the story through expert spatial orchestration.
+
+**"Geometric Silence"**
+Philosophy: Pure order and restraint.
+Visual expression: Grid-based precision, bold photography or stark graphics, dramatic negative space. Typography precise but minimal - small essential text, large quiet zones. Swiss formalism meets Brutalist material honesty. Structure communicates, not words. Every alignment the work of countless refinements.

package/templates/.claude/skills/debugging-toolkit/SKILL.md

@@ -53,28 +53,7 @@ You MUST complete each phase before proceeding to the next.
    - Git diff, recent commits
    - New dependencies, config changes
 
-4. **Root Cause Tracing (Deep Dive)**
-
-   **Use when error is deep in call stack:**
-
-   **The Tracing Process:**
-   1. **Observe Symptom:** `Error: git init failed in /packages/core`
-   2. **Find Immediate Cause:** `execFile('git', ['init'], { cwd: '' })`
-   3. **Trace Upwards:**
-      - Who called this? `WorktreeManager`
-      - With what arguments? `projectDir = ''`
-   4. **Find Original Trigger:**
-      - Where did empty string come from? `setupCoreTest()` returned empty `tempDir`
-   5. **Fix at Source:** Fix `setupCoreTest`, NOT the immediate caller.
-
-   **Instrumentation:**
-   If manual tracing fails, add logging *before* the failure:
-   ```js
-   console.error('DEBUG context:', {
-     arg: someArg,
-     stack: new Error().stack // crucial!
-   });
-   ```
+4. **Root Cause Tracing (Deep Dive)** — use when error is deep in call stack: trace upwards from symptom to original trigger, fix at source. Worked example + instrumentation snippet: [`reference-tables.md`](reference-tables.md#root-cause-tracing-deep-dive).
 
 5. **Gather Evidence in Multi-Component Systems**
    - Log what enters/exits each component boundary
@@ -146,11 +125,4 @@ If you catch yourself thinking:
 
 **ALL of these mean: STOP. Return to Phase 1.**
 
-## Quick Reference
-
-| Phase | Key Activities | Success Criteria |
-|-------|---------------|------------------|
-| **1. Root Cause** | Read errors, reproduce, trace stack backwards | Understand WHAT and WHY |
-| **2. Pattern** | Find working examples, compare | Identify differences |
-| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
-| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+Compact per-phase quick-reference table: [`reference-tables.md`](reference-tables.md).

package/templates/.claude/skills/debugging-toolkit/reference-tables.md

@@ -0,0 +1,33 @@
+# Debugging Toolkit — Quick Reference
+
+Compact restatement of the four phases in `SKILL.md`. Read the phases first; this table is for quick lookup during a session.
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, trace stack backwards | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## Root Cause Tracing (Deep Dive)
+
+**The Tracing Process:**
+1. **Observe Symptom:** `Error: git init failed in /packages/core`
+2. **Find Immediate Cause:** `execFile('git', ['init'], { cwd: '' })`
+3. **Trace Upwards:**
+   - Who called this? `WorktreeManager`
+   - With what arguments? `projectDir = ''`
+4. **Find Original Trigger:**
+   - Where did empty string come from? `setupCoreTest()` returned empty `tempDir`
+5. **Fix at Source:** Fix `setupCoreTest`, NOT the immediate caller.
+
+**Instrumentation:**
+If manual tracing fails, add logging *before* the failure:
+```js
+console.error('DEBUG context:', {
+  arg: someArg,
+  stack: new Error().stack // crucial!
+});
+```

package/templates/.claude/skills/docs-manager/SKILL.md

@@ -20,63 +20,7 @@ AI agent NÊN dùng skill này khi:
 
 ## Documentation Structure
 
-Mọi project sử dụng skill này PHẢI có folder `docs/` với cấu trúc:
-
-```
-docs/
-├── README.md                    # 🎯 BẮT ĐẦU TẠI ĐÂY - Navigation hub
-├── project.md                   # 📋 Project overview
-├── memory.md                    # 🧠 Decisions & context log
-│
-├── architecture/                # 🏗️ System design
-│   ├── overview.md             # Architecture tổng quan
-│   ├── tech-stack.md           # Technologies sử dụng
-│   ├── data-model.md           # Database schema
-│   ├── api-design.md           # API specifications
-│   └── deployment.md           # Infrastructure
-│
-├── agents/                      # 🤖 Multi-agent coordination
-│   ├── agent-roles.md          # Vai trò từng agent
-│   ├── orchestration.md        # Flow điều phối
-│   ├── prompts/                # System prompts
-│   │   ├── architect.md
-│   │   ├── coder.md
-│   │   ├── debugger.md
-│   │   └── orchestrator.md
-│   └── handoff-rules.md        # Quy tắc chuyển giao
-│
-├── standards/                   # 📏 Coding standards
-│   ├── coding-conventions.md   # Code style
-│   ├── commit-conventions.md   # Git conventions
-│   ├── file-structure.md       # File organization
-│   ├── error-handling.md       # Error handling
-│   └── security.md             # Security rules
-│
-├── workflows/                   # 🔄 Development processes
-│   ├── development.md          # Feature development flow
-│   ├── debugging.md            # Debug process
-│   ├── testing.md              # Testing strategy
-│   ├── deployment.md           # Deployment process
-│   └── code-review.md          # Review checklist
-│
-├── context/                     # 📚 Business context
-│   ├── business-rules.md       # Business logic
-│   ├── constraints.md          # Technical constraints
-│   ├── dependencies.md         # External dependencies
-│   └── known-issues.md         # Known issues & workarounds
-│
-├── guides/                      # 📖 How-to guides
-│   ├── onboarding.md           # AI onboarding
-│   ├── quick-start.md          # Quick setup
-│   ├── troubleshooting.md      # Common problems
-│   └── faq.md                  # FAQs
-│
-└── models/                      # 🧠 AI model configs
-    ├── model-configs.md        # Model configurations
-    ├── model-selection.md      # When to use which model
-    ├── token-optimization.md   # Token optimization
-    └── fallback-strategy.md    # Fallback handling
-```
+Mọi project sử dụng skill này PHẢI có folder `docs/` theo cấu trúc chuẩn (README, project, memory, architecture/, agents/, standards/, workflows/, context/, guides/, models/). Full tree: [`conventions-and-examples.md`](conventions-and-examples.md#documentation-structure).
 
 ## Workflow: How AI Should Use This Skill
 
@@ -197,213 +141,27 @@ cat docs/architecture/data-model.md
 
 ## Key Principles
 
-### ✅ DO (LUÔN LÀM)
-
-1. **Đọc docs TRƯỚC KHI code**
-   - README.md → project.md → memory.md → standards/
-   - Không bao giờ skip bước này
-
-2. **Follow conventions NGHIÊM NGẶT**
-   - Code style from `standards/coding-conventions.md`
-   - Database rules from `architecture/data-model.md`
-   - Git commits from `standards/commit-conventions.md`
-
-3. **Document EVERYTHING quan trọng**
-   - Decisions → memory.md
-   - Issues → context/known-issues.md
-   - Architecture changes → architecture/
-
-4. **Cross-reference docs**
-   - Khi đọc 1 file, note references đến files khác
-   - Build mental map của toàn bộ docs
-
-5. **Update proactively**
-   - Tìm thấy thông tin mới? Update docs ngay
-   - Không để docs outdated
+**DO**: đọc docs trước khi code (README → project → memory → standards, không skip); follow conventions nghiêm ngặt (code style, DB rules, commit conventions); document mọi decision/issue/architecture change ngay khi phát sinh; cross-reference giữa các file để build mental map; update docs proactively khi có thông tin mới.
 
-### ❌ DON'T (TUYỆT ĐỐI TRÁNH)
-
-1. **Không skip đọc docs**
-   - Đừng assume bạn biết project
-   - Đừng code trước khi đọc conventions
-
-2. **Không violate conventions**
-   - Không tự ý thay đổi code style
-   - Không bỏ qua architecture constraints
-
-3. **Không quên document**
-   - Không để decisions chỉ trong chat
-   - Không quên update memory.md
-
-4. **Không duplicate info**
-   - Check docs trước khi thêm mới
-   - Consolidate thay vì scatter
+**DON'T**: đừng code trước khi đọc conventions; đừng tự ý đổi code style hay bỏ qua architecture constraints; đừng để decision chỉ nằm trong chat mà không ghi vào memory.md; đừng duplicate thông tin — check docs trước khi thêm mới, consolidate thay vì scatter.
 
 ---
 
-## Code Conventions (From docs/standards/coding-conventions.md)
-
-### Database Rules
-
-```javascript
-// ✅ ĐÚNG: UUID primary keys
-id: {
-  type: DataTypes.UUID,
-  defaultValue: DataTypes.UUIDV4,
-  primaryKey: true
-}
-
-// ❌ SAI: Auto-increment
-id: {
-  type: DataTypes.INTEGER,
-  autoIncrement: true,
-  primaryKey: true
-}
-
-// ✅ ĐÚNG: No foreign key constraints
-user_id: {
-  type: DataTypes.UUID,
-  allowNull: false
-}
-
-// ❌ SAI: With FK constraint
-user_id: {
-  type: DataTypes.UUID,
-  references: { model: 'users', key: 'id' }
-}
-```
-
-### Oracle Schema Prefix
-
-```sql
--- ✅ ĐÚNG: With schema prefix
-SELECT * FROM APPS.MTL_SYSTEM_ITEMS_B
-
--- ❌ SAI: Without prefix
-SELECT * FROM MTL_SYSTEM_ITEMS_B
-```
-
-### Naming Conventions
-
-```javascript
-// Variables & Functions: camelCase
-const userName = "LeNK";
-function getUserData() {}
-
-// Classes: PascalCase
-class UserService {}
+## Code Conventions
 
-// Constants: UPPER_SNAKE_CASE
-const API_BASE_URL = "https://api.example.com";
-
-// Files: kebab-case
-user - service.js;
-
-// DB tables/columns: snake_case
-(users, user_profiles, created_at);
-```
+UUID primary keys (not auto-increment), no FK constraints, Oracle schema prefixes, and JS/SQL naming patterns: [`conventions-and-examples.md`](conventions-and-examples.md).
 
 ---
 
 ## Agent Coordination
 
-### Agent Roles (From docs/agents/agent-roles.md)
-
-**Architect Agent**
-
-- Design system architecture
-- Make technical decisions
-- Review architectural changes
-
-**Coder Agent**
-
-- Implement features
-- Write tests
-- Follow coding standards
-
-**Debugger Agent**
-
-- Analyze bugs
-- Find root causes
-- Verify fixes
-
-**Orchestrator Agent**
-
-- Break down tasks
-- Coordinate agents
-- Track progress
-
-### Handoff Rules
-
-**Khi nào handoff?**
-
-- Architect → Coder: Sau khi design xong
-- Coder → Debugger: Khi gặp bug
-- Debugger → Architect: Bug do design issue
-- Any → Orchestrator: Task phức tạp cần break down
-
-**Trước khi handoff:**
-
-1. Update `docs/memory.md` với context
-2. Summarize work done
-3. List blockers/questions
-4. Point to relevant docs
+Four agent roles (Architect, Coder, Debugger, Orchestrator) and handoff-trigger rules: [`conventions-and-examples.md`](conventions-and-examples.md#agent-coordination).
 
 ---
 
 ## Examples
 
-### Example 1: Starting New Feature
-
-```bash
-# User request: "Add user authentication"
-
-# Step 1: Load context
-cat docs/README.md
-cat docs/project.md
-cat docs/memory.md
-
-# Step 2: Check if similar feature exists
-grep -r "authentication" docs/memory.md
-cat docs/context/known-issues.md
-
-# Step 3: Load relevant docs
-cat docs/architecture/overview.md
-cat docs/architecture/data-model.md
-cat docs/standards/coding-conventions.md
-cat docs/standards/security.md
-
-# Step 4: Check workflows
-cat docs/workflows/development.md
-
-# Step 5: Start development following conventions
-
-# Step 6: Document decision
-echo "## [2025-01-24] - User Authentication
-**Context**: Need secure user auth
-**Decision**: Using bcrypt + JWT
-**Impact**: New users table, auth middleware
-**Next**: Implement signup/login endpoints" >> docs/memory.md
-```
-
-### Example 2: Debugging Issue
-
-```bash
-# User: "PostgreSQL auto-increment not working"
-
-# Step 1: Check known issues
-cat docs/context/known-issues.md
-
-# Step 2: Check conventions
-cat docs/standards/coding-conventions.md
-# → Found: We use UUID, not auto-increment!
-
-# Step 3: Check memory for similar cases
-grep -r "auto-increment\|UUID" docs/memory.md
-
-# Step 4: Provide solution based on conventions
-# Step 5: Update docs if needed
-```
+Two worked examples (starting a new feature, debugging an issue) walking through which docs to load and when to write to `memory.md`: [`conventions-and-examples.md`](conventions-and-examples.md).
 
 ---