@champpaba/claude-agent-kit 1.7.0 → 1.7.1

package/.claude/CLAUDE.md

@@ -1,11 +1,49 @@
 # CLAUDE.md
 
 > **Navigation Hub for AI Agents**
-> **Template Version:** 1.7.0 - Universal Multi-Agent Template (Opus 4.5)
+> **Template Version:** 1.7.1 - Universal Multi-Agent Template (Opus 4.5)
 > **Latest:** Incremental Testing - Milestone-based validation for high-risk tasks with round-based retry
 
 ---
 
+## 📁 File Naming Conventions (OpenSpec + Template)
+
+> **IMPORTANT:** Avoid confusion between OpenSpec files and Template files
+
+### OpenSpec Files (from [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec))
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `proposal.md` | WHY - Goals, scope, rationale | Phase planning |
+| `tasks.md` | WHAT - Implementation checklist | Task tracking |
+| `design.md` | **Technical/Architecture decisions** (optional) | Backend/Database phases |
+| `specs/` | Delta specs (ADDED/MODIFIED/REMOVED) | Requirement validation |
+
+### Template Files (from claude-multi-agent-template)
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `STYLE_GUIDE.md` | **Visual design** (colors, typography, spacing) | UI/Frontend phases |
+| `STYLE_TOKENS.json` | Lightweight design tokens (~500 tokens) | Quick UI reference |
+| `page-plan.md` | UI component layout + content strategy | uxui-frontend agent |
+| `phases.md` | Execution plan with agent assignments | All phases |
+| `flags.json` | Progress tracking | All phases |
+
+### Key Distinction
+
+```
+OpenSpec design.md    = Technical Architecture (data flow, API structure, system design)
+Template STYLE_GUIDE  = Visual Design (colors, fonts, spacing, component styles)
+```
+
+**Agents should read BOTH when relevant:**
+- `uxui-frontend` → STYLE_GUIDE.md (visual) + design.md (if has UI architecture)
+- `backend` → design.md (API/data architecture)
+- `database` → design.md (data models, relationships)
+- `frontend` → STYLE_GUIDE.md (visual) + design.md (API contracts)
+
+---
+
 ## 🎯 What is This Template?
 
 Universal, framework-agnostic template for AI-assisted development.

package/.claude/contexts/patterns/agent-discovery.md

@@ -104,11 +104,15 @@ ls openspec/changes/{change-id}/.claude/
 
 4. **OpenSpec files:**
    ```bash
-   Read: openspec/changes/{change-id}/proposal.md
-   Read: openspec/changes/{change-id}/tasks.md
-   Read: openspec/changes/{change-id}/design.md  # if exists
+   Read: openspec/changes/{change-id}/proposal.md   # WHY - goals, scope
+   Read: openspec/changes/{change-id}/tasks.md      # WHAT - checklist
+   Read: openspec/changes/{change-id}/design.md     # HOW - technical architecture (if exists)
    ```
 
+   > **Note:** `design.md` = Technical/Architecture decisions (API structure, data flow)
+   > This is DIFFERENT from `STYLE_GUIDE.md` which is Visual Design (colors, fonts)
+   > See CLAUDE.md "File Naming Conventions" for details.
+
 **If change context doesn't exist:**
 - Skip Level 5 (working on general task, not OpenSpec change)
 

package/README.md

@@ -917,7 +917,37 @@ Built with:
 
 ---
 
-## 🆕 What's New in v1.7.0
+## 🆕 What's New in v1.7.1
+
+**Patch: OpenSpec File Naming Conventions - Clarify design.md vs STYLE_GUIDE.md** 📁
+
+### The Issue
+
+Users were confused between two files with similar names:
+- `design.md` (from OpenSpec) = Technical/Architecture decisions
+- `STYLE_GUIDE.md` (from Template) = Visual design (colors, fonts, spacing)
+
+### The Fix
+
+Added clear documentation in CLAUDE.md and agent-discovery.md:
+
+| Source | File | Purpose |
+|--------|------|---------|
+| **OpenSpec** | `design.md` | Technical Architecture (API structure, data flow) |
+| **Template** | `STYLE_GUIDE.md` | Visual Design (colors, typography, spacing) |
+
+### Updated Files
+
+- `CLAUDE.md` - New "📁 File Naming Conventions" section
+- `agent-discovery.md` - Added notes explaining design.md vs STYLE_GUIDE.md
+
+### No Breaking Changes
+
+All existing workflows continue to work. This is a documentation improvement only.
+
+---
+
+## 📋 What's New in v1.7.0
 
 **Feature: Opus 4.5 Model Upgrade - All Subagents Now Use Latest Claude Model** 🧠
 
@@ -1192,6 +1222,19 @@ All your customizations in `.claude/contexts/domain/` are preserved!
 
 ## 📜 Changelog
 
+### v1.7.1 (2025-11-25)
+**Patch: OpenSpec File Naming Conventions**
+
+**Added:**
+- New "📁 File Naming Conventions" section in CLAUDE.md
+- Clear distinction between OpenSpec files and Template files
+- Notes in agent-discovery.md explaining design.md purpose
+
+**Documentation:**
+- `design.md` (OpenSpec) = Technical Architecture (API, data flow)
+- `STYLE_GUIDE.md` (Template) = Visual Design (colors, fonts, spacing)
+- Updated agent reading guidance per role
+
 ### v1.7.0 (2025-11-25)
 **Feature: Opus 4.5 Model Upgrade**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@champpaba/claude-agent-kit",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Universal multi-agent template for Claude Code - AI-assisted development with specialized agents",
   "main": "bin/cli.js",
   "bin": {