scene-capability-engine 3.0.0

package/locales/en.json

@@ -0,0 +1,114 @@
+{
+  "cli": {
+    "name": "sce",
+    "description": "🔥 SCE (Scene Capability Engine) - Structured AI delivery with Specs, orchestration, and KPI observability",
+    "commands": {
+      "init": {
+        "description": "Initialize a new SCE project",
+        "projectNamePrompt": "Enter project name:",
+        "forceOption": "Force initialization even if .kiro directory exists",
+        "alreadyExists": "⚠️  .kiro directory already exists",
+        "overwritePrompt": "Do you want to overwrite it?",
+        "cancelled": "Initialization cancelled.",
+        "success": "🎉 SCE project initialized successfully!",
+        "nextSteps": "📋 Next steps:",
+        "step1": "Create your first spec: mkdir .kiro/specs/01-00-your-feature",
+        "step2": "Write basic requirements.md",
+        "step3": "Enhance with Ultrawork: sce enhance requirements .kiro/specs/01-00-your-feature/requirements.md",
+        "startJourney": "🔥 Start your Ultrawork journey!",
+        "error": "❌ Error initializing project:"
+      },
+      "enhance": {
+        "description": "Enhance document quality with Ultrawork spirit",
+        "starting": "🔥 Starting {stage} stage Ultrawork enhancement...",
+        "toolNotFound": "❌ Ultrawork tool not found. Please run: sce init",
+        "completed": "✅ Ultrawork enhancement completed!",
+        "failed": "❌ Enhancement failed with code:",
+        "pythonError": "❌ Error running Python tool:",
+        "pythonTip": "💡 Make sure Python 3.8+ is installed and in PATH"
+      },
+      "createSpec": {
+        "description": "Create a new spec directory",
+        "success": "✅ Created spec directory:",
+        "nextSteps": "📋 Next steps:",
+        "step1": "Create requirements.md in the spec directory",
+        "step2": "Enhance with: sce enhance requirements {specPath}/requirements.md",
+        "error": "❌ Error creating spec:"
+      },
+      "status": {
+        "description": "Check project status and available specs",
+        "noProject": "⚠️  No SCE project found in current directory",
+        "initTip": "Run: sce init to initialize",
+        "title": "🔥 SCE Project Status",
+        "toolStatus": "Ultrawork Tool:",
+        "available": "✅ Available",
+        "missing": "❌ Missing",
+        "specsTitle": "📋 Available Specs:",
+        "noSpecs": "No specs found",
+        "requirements": "Requirements:",
+        "design": "Design:",
+        "tasks": "Tasks:"
+      },
+      "doctor": {
+        "description": "Check system requirements and diagnostics",
+        "title": "System Diagnostics",
+        "checking": "Checking system requirements...",
+        "nodejs": "Node.js",
+        "python": "Python",
+        "python_note": "Note: Python is required for Ultrawork quality enhancement features.",
+        "all_good": "All system requirements are met!",
+        "ready": "You're ready to use all SCE features including Ultrawork enhancements.",
+        "python_missing": "Python is not available",
+        "basic_features": "Basic CLI features (init, status, create-spec) will work normally.",
+        "ultrawork_unavailable": "Ultrawork enhancement features require Python 3.8 or higher."
+      }
+    }
+  },
+  "ultrawork": {
+    "spirit": {
+      "title": "🔥 Ultrawork Spirit",
+      "subtitle": "Like Sisyphus pushing the boulder up the mountain",
+      "principles": {
+        "relentless": "Never give up, relentless effort",
+        "excellence": "Pursue professional-grade quality",
+        "improvement": "Continuous improvement and optimization",
+        "completion": "Perfect completion of every task"
+      }
+    },
+    "quality": {
+      "scoring": "Quality Scoring: {score}/10",
+      "professional": "✅ Document has reached professional standards!",
+      "improving": "🔄 Round {iteration} improvement: {improvements}",
+      "noImprovements": "⚠️ No more improvements identified, stopping iteration",
+      "scoreNotImproved": "⚠️ Quality score not improved, stopping iteration"
+    },
+    "stages": {
+      "requirements": "Requirements",
+      "design": "Design",
+      "tasks": "Tasks"
+    }
+  },
+  "messages": {
+    "success": "✅ Success",
+    "error": "❌ Error",
+    "warning": "⚠️ Warning",
+    "info": "💡 Info",
+    "processing": "🔄 Processing",
+    "completed": "🎉 Completed"
+  },
+  "python": {
+    "available": "Python {version} is available",
+    "not_found": "Python is not installed or not found in PATH",
+    "version_too_old": "Python {version} is installed, but version {required} or higher is required",
+    "malformed_version": "Unable to parse Python version: {version}",
+    "error_header": "✗ Python is required for Ultrawork quality enhancement features",
+    "install_header": "Installation instructions:",
+    "help_footer": "For more help, visit: https://github.com/USERNAME/kiro-spec-engine#python-setup",
+    "install": {
+      "windows": "Windows:\n1. Download Python from https://www.python.org/downloads/\n2. Run the installer and check 'Add Python to PATH'\n3. Restart your terminal and run: python --version",
+      "macos": "macOS:\n1. Install Homebrew if not already installed: /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n2. Install Python: brew install python\n3. Verify installation: python3 --version",
+      "linux": "Linux:\n1. Ubuntu/Debian: sudo apt-get update && sudo apt-get install python3 python3-pip\n2. Fedora/RHEL: sudo dnf install python3 python3-pip\n3. Verify installation: python3 --version",
+      "default": "Please visit https://www.python.org/downloads/ to download and install Python 3.8 or higher for your operating system."
+    }
+  }
+}

package/locales/zh.json

@@ -0,0 +1,114 @@
+{
+  "cli": {
+    "name": "sce",
+    "description": "🔥 SCE（场景能力引擎）- 以 Spec、编排与 KPI 可观测驱动 AI 交付",
+    "commands": {
+      "init": {
+        "description": "初始化新的 SCE（场景能力引擎）项目",
+        "projectNamePrompt": "请输入项目名称:",
+        "forceOption": "强制初始化，即使 .kiro 目录已存在",
+        "alreadyExists": "⚠️  .kiro 目录已存在",
+        "overwritePrompt": "是否要覆盖它？",
+        "cancelled": "初始化已取消。",
+        "success": "🎉 SCE 项目初始化成功！",
+        "nextSteps": "📋 下一步操作:",
+        "step1": "创建第一个 Spec: mkdir .kiro/specs/01-00-your-feature",
+        "step2": "编写基础 requirements.md",
+        "step3": "使用 Ultrawork 增强: sce enhance requirements .kiro/specs/01-00-your-feature/requirements.md",
+        "startJourney": "🔥 开始你的 Ultrawork 之旅！",
+        "error": "❌ 初始化项目时出错:"
+      },
+      "enhance": {
+        "description": "使用 Ultrawork 精神增强文档质量",
+        "starting": "🔥 启动 {stage} 阶段 Ultrawork 增强...",
+        "toolNotFound": "❌ 找不到 Ultrawork 工具。请运行: sce init",
+        "completed": "✅ Ultrawork 增强完成！",
+        "failed": "❌ 增强失败，错误代码:",
+        "pythonError": "❌ 运行 Python 工具时出错:",
+        "pythonTip": "💡 请确保已安装 Python 3.8+ 并在 PATH 中"
+      },
+      "createSpec": {
+        "description": "创建新的 Spec 目录",
+        "success": "✅ 已创建 Spec 目录:",
+        "nextSteps": "📋 下一步操作:",
+        "step1": "在 Spec 目录中创建 requirements.md",
+        "step2": "使用以下命令增强: sce enhance requirements {specPath}/requirements.md",
+        "error": "❌ 创建 Spec 时出错:"
+      },
+      "status": {
+        "description": "检查项目状态和可用的 Specs",
+        "noProject": "⚠️  当前目录中未找到 SCE 项目",
+        "initTip": "运行: sce init 来初始化",
+        "title": "🔥 SCE 项目状态",
+        "toolStatus": "Ultrawork 工具:",
+        "available": "✅ 可用",
+        "missing": "❌ 缺失",
+        "specsTitle": "📋 可用的 Specs:",
+        "noSpecs": "未找到 Specs",
+        "requirements": "需求文档:",
+        "design": "设计文档:",
+        "tasks": "任务文档:"
+      },
+      "doctor": {
+        "description": "检查系统要求和诊断信息",
+        "title": "系统诊断",
+        "checking": "正在检查系统要求...",
+        "nodejs": "Node.js",
+        "python": "Python",
+        "python_note": "注意: Ultrawork 质量增强功能需要 Python。",
+        "all_good": "所有系统要求均已满足！",
+        "ready": "您已准备好使用 SCE 的所有功能，包括 Ultrawork 增强。",
+        "python_missing": "Python 不可用",
+        "basic_features": "基本 CLI 功能（init、status、create-spec）可以正常工作。",
+        "ultrawork_unavailable": "Ultrawork 增强功能需要 Python 3.8 或更高版本。"
+      }
+    }
+  },
+  "ultrawork": {
+    "spirit": {
+      "title": "🔥 Ultrawork 精神",
+      "subtitle": "像西西弗斯推石上山一样",
+      "principles": {
+        "relentless": "永不放弃，不懈努力",
+        "excellence": "追求专业级质量",
+        "improvement": "持续改进和优化",
+        "completion": "完美完成每个任务"
+      }
+    },
+    "quality": {
+      "scoring": "质量评分: {score}/10",
+      "professional": "✅ 文档已达到专业级标准！",
+      "improving": "🔄 第 {iteration} 轮改进: {improvements}",
+      "noImprovements": "⚠️ 无法识别更多改进点，停止迭代",
+      "scoreNotImproved": "⚠️ 质量评分未提升，停止迭代"
+    },
+    "stages": {
+      "requirements": "需求",
+      "design": "设计",
+      "tasks": "任务"
+    }
+  },
+  "messages": {
+    "success": "✅ 成功",
+    "error": "❌ 错误",
+    "warning": "⚠️ 警告",
+    "info": "💡 提示",
+    "processing": "🔄 处理中",
+    "completed": "🎉 完成"
+  },
+  "python": {
+    "available": "Python {version} 可用",
+    "not_found": "未安装 Python 或 Python 不在 PATH 中",
+    "version_too_old": "已安装 Python {version}，但需要 {required} 或更高版本",
+    "malformed_version": "无法解析 Python 版本: {version}",
+    "error_header": "✗ Ultrawork 质量增强功能需要 Python",
+    "install_header": "安装说明:",
+    "help_footer": "获取更多帮助，请访问: https://github.com/USERNAME/kiro-spec-engine#python-setup",
+    "install": {
+      "windows": "Windows:\n1. 从 https://www.python.org/downloads/ 下载 Python\n2. 运行安装程序并勾选 'Add Python to PATH'\n3. 重启终端并运行: python --version",
+      "macos": "macOS:\n1. 如果尚未安装 Homebrew，请先安装: /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n2. 安装 Python: brew install python\n3. 验证安装: python3 --version",
+      "linux": "Linux:\n1. Ubuntu/Debian: sudo apt-get update && sudo apt-get install python3 python3-pip\n2. Fedora/RHEL: sudo dnf install python3 python3-pip\n3. 验证安装: python3 --version",
+      "default": "请访问 https://www.python.org/downloads/ 下载并安装适合您操作系统的 Python 3.8 或更高版本。"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "scene-capability-engine",
+  "version": "3.0.0",
+  "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
+  "main": "index.js",
+  "bin": {
+    "sce": "bin/sce.js",
+    "sco": "bin/sco.js",
+    "kse": "bin/kse.js",
+    "kiro-spec-engine": "bin/kiro-spec-engine.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "template/",
+    "!template/.kiro/tools/__pycache__/",
+    "!template/.kiro/tools/**/*.pyc",
+    "!template/.kiro/tools/**/*.pyo",
+    "!template/.kiro/tools/**/*.pyd",
+    "locales/",
+    "docs/",
+    "README.md",
+    "README.zh.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "npx jest",
+    "test:smoke": "npm run test:ci",
+    "test:full": "npx jest --config=jest.config.js",
+    "test:ci": "npx jest --config=jest.config.ci.js",
+    "test:unit": "npx jest tests/unit",
+    "test:integration": "npx jest tests/integration",
+    "test:properties": "npx jest tests/properties",
+    "test:handles": "npx jest --config=jest.config.js --runInBand --detectOpenHandles",
+    "test:skip-audit": "node scripts/check-skip-allowlist.js",
+    "test:watch": "npx jest --watch",
+    "coverage": "npx jest --coverage",
+    "report:moqui-baseline": "node scripts/moqui-template-baseline-report.js --json",
+    "report:moqui-core-regression": "node scripts/moqui-core-regression-suite.js --json",
+    "prepublishOnly": "npm run test:full && npm run test:skip-audit",
+    "publish:manual": "npm publish --access public",
+    "install-global": "npm install -g .",
+    "uninstall-global": "npm uninstall -g scene-capability-engine"
+  },
+  "keywords": [
+    "kiro",
+    "spec",
+    "spec-driven",
+    "engine",
+    "steering",
+    "rules-engine",
+    "development",
+    "quality",
+    "ultrawork",
+    "ai",
+    "productivity",
+    "cli",
+    "i18n",
+    "multilingual",
+    "chinese",
+    "english",
+    "development-tools",
+    "quality-enhancement",
+    "sisyphus",
+    "sco",
+    "scene",
+    "sce",
+    "scene-capability-engine"
+  ],
+  "author": "heguangyong",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heguangyong/scene-capability-engine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/heguangyong/scene-capability-engine/issues"
+  },
+  "homepage": "https://github.com/heguangyong/scene-capability-engine#readme",
+  "engines": {
+    "node": ">=16.0.0",
+    "python": ">=3.8.0"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "chokidar": "^3.5.3",
+    "cli-table3": "^0.6.5",
+    "commander": "^9.0.0",
+    "fs-extra": "^10.0.0",
+    "inquirer": "^8.2.0",
+    "js-yaml": "^4.1.1",
+    "minimatch": "^10.1.1",
+    "path": "^0.12.7",
+    "semver": "^7.5.4",
+    "simple-git": "^3.30.0"
+  },
+  "devDependencies": {
+    "fast-check": "^4.5.3",
+    "jest": "^27.5.1"
+  }
+}

package/template/.kiro/README.md

@@ -0,0 +1,247 @@
+# Project Development Guide
+
+> **AI Tools: Read this first!** This project follows Spec-driven development methodology powered by kse (Kiro Spec Engine).
+
+---
+
+## 🎯 How This Project Works
+
+This project uses **Spec-driven development** - a structured approach where:
+- Every feature starts with a **Spec** (requirements + design + tasks)
+- All work is tracked and documented
+- AI tools help implement features according to Specs
+
+**Your role as AI:**
+- When user requests a feature → Check if Spec exists, if not, help create one
+- When implementing → Follow the Spec's requirements and design
+- When stuck → Read the Spec documents for context
+- Track progress by updating task status
+
+---
+
+## 🚀 kse Capabilities (v1.45.x)
+
+**IMPORTANT**: After installing or updating kse, read this section to understand all available capabilities. Using the right tool for the job ensures efficient, high-quality development.
+
+### Core: Spec-Driven Development
+- `kse adopt` — Initialize kse in a project (creates `.kiro/` structure)
+- `kse create-spec <name>` — Create a new Spec (requirements + design + tasks)
+- `kse status` — Show project status and Spec progress
+- `kse workflows` — List available Specs and workflows
+- `kse context export <spec-name>` — Export Spec context for AI consumption
+- `kse prompt generate <spec> <task>` — Generate task-specific prompt
+
+### Task Management
+- `kse task claim <spec> <task-id>` — Claim a task for execution
+- `kse task list <spec>` — List claimed tasks
+- Task status tracking in `tasks.md`: `[ ]` not started, `[-]` in progress, `[x]` completed
+
+### Spec Locking (Multi-User)
+- `kse lock acquire <spec>` — Lock a Spec to prevent conflicts
+- `kse lock release <spec>` / `kse unlock <spec>` — Release lock
+- `kse lock status` — Check lock status
+- `kse lock cleanup` — Remove stale locks (24h timeout)
+- `kse lock whoami` — Show machine identifier
+
+### Workspace Management
+- `kse workspace create/list/switch/info/remove` — Manage multiple kse projects
+- Global state: `~/.kse/workspace-state.json`
+
+### Environment Configuration
+- `kse env list/switch/info/register/unregister/rollback/verify/run` — Multi-environment management
+- Automatic backup before each switch, instant rollback support
+
+### Multi-Repository Management
+- `kse repo init [--nested]` — Auto-discover Git repositories
+- `kse repo status [--verbose]` — Status of all repositories
+- `kse repo exec "<command>"` — Execute command across all repos
+- `kse repo health` — Check repository health
+
+### Spec-Level Collaboration
+- `kse collab init/status/assign/verify/integrate/migrate` — Coordinate parallel Spec development
+- Master Spec + Sub-Specs with dependency management
+- Interface contracts for cross-Spec compatibility
+
+### Multi-Agent Parallel Coordination (v1.43.0)
+When multiple AI agents work on the same project simultaneously:
+- **AgentRegistry** (`lib/collab`) — Agent lifecycle with heartbeat monitoring
+- **TaskLockManager** (`lib/lock`) — File-based task mutual exclusion
+- **TaskStatusStore** (`lib/task`) — Concurrent-safe tasks.md updates with retry
+- **SteeringFileLock** (`lib/lock`) — Steering file write serialization
+- **MergeCoordinator** (`lib/collab`) — Git branch isolation per agent
+- **Coordinator** (`lib/collab`) — Central task assignment (optional)
+- Config: `.kiro/config/multi-agent.json` (`enabled: true` to activate)
+- All components are no-ops in single-agent mode (zero overhead)
+- See `docs/multi-agent-coordination-guide.md` for full API reference
+
+### Spec-Level Steering & Context Sync (v1.44.0)
+Fourth steering layer (L4) and Spec lifecycle coordination for multi-agent scenarios:
+- **SpecSteering** (`lib/steering`) — Per-Spec `steering.md` CRUD with template generation, Markdown ↔ structured object roundtrip
+- **SteeringLoader** (`lib/steering`) — Unified L1-L4 four-layer steering loader with merged output
+- **ContextSyncManager** (`lib/steering`) — Multi-agent CURRENT_CONTEXT.md maintenance with Spec progress table, SteeringFileLock-protected writes
+- **SpecLifecycleManager** (`lib/collab`) — Spec state machine (planned → assigned → in-progress → completed → released) with auto-completion detection
+- **SyncBarrier** (`lib/collab`) — Agent Spec-switch synchronization barrier (uncommitted changes check, steering reload)
+- **Coordinator Integration** — `completeTask` auto-checks Spec completion; `assignTask` runs SyncBarrier
+- All components are no-ops in single-agent mode (zero overhead)
+- See `docs/multi-agent-coordination-guide.md` for full API reference
+
+### Autonomous Control
+- `kse auto create <description>` — Create and execute Spec autonomously
+- `kse auto run <spec>` — Execute existing Spec tasks autonomously
+- `kse auto status/resume/stop/config` — Manage autonomous execution
+- Intelligent error recovery, checkpoint system, learning from history
+
+### Agent Orchestrator — Multi-Agent Spec Execution (v1.45.0)
+Automate parallel Spec execution via Codex CLI sub-agents (replaces manual multi-terminal workflow):
+- `kse orchestrate run --specs "spec-a,spec-b,spec-c" --max-parallel 3` — Start multi-agent orchestration
+- `kse orchestrate status` — View orchestration progress (per-Spec status, overall state)
+- `kse orchestrate stop` — Gracefully stop all sub-agents
+- **OrchestratorConfig** (`lib/orchestrator`) — Configuration management (agent backend, parallelism, timeout, retries) via `.kiro/config/orchestrator.json`
+- **BootstrapPromptBuilder** (`lib/orchestrator`) — Builds bootstrap prompts with Spec path, steering context, execution instructions
+- **AgentSpawner** (`lib/orchestrator`) — Process manager for Codex CLI sub-agents with timeout detection, graceful termination (SIGTERM → SIGKILL)
+- **StatusMonitor** (`lib/orchestrator`) — Codex JSON Lines event parsing, per-Spec status tracking, orchestration-level aggregation
+- **OrchestrationEngine** (`lib/orchestrator`) — DAG-based dependency analysis, batch scheduling, parallel execution (≤ maxParallel), failure propagation, retry mechanism
+- Prerequisites: Codex CLI installed, `CODEX_API_KEY` environment variable set
+- 11 correctness properties verified via property-based testing
+
+### Scene Runtime (Template Engine + Quality + ERP)
+- **Template Engine**: `kse scene template-validate/resolve/render` — Variable schema, multi-file rendering, 3-layer inheritance
+- **Package Registry**: `kse scene publish/unpublish/install/list/search/info/diff/version` — Local package management
+- **Quality Pipeline**: `kse scene lint/score/contribute` — 10-category lint, quality scoring, one-stop publish
+- **Ontology**: `kse scene ontology show/deps/validate/actions/lineage/agent-info` — Semantic relationship graph
+- **Moqui ERP**: `kse scene connect/discover/extract` — ERP integration and template extraction
+- **Registry Ops**: `kse scene deprecate/audit/owner/tag/lock/stats` — Advanced registry management
+
+### Document Governance
+- `kse docs diagnose/cleanup/validate/archive/hooks` — Document lifecycle management
+- Automatic compliance checking and cleanup
+
+### DevOps Integration
+- `kse ops init/validate/audit/takeover/feedback` — Operations Spec management
+- Progressive AI autonomy levels (L1-L5)
+
+### Knowledge Management
+- `kse knowledge init/add/list/search/show/delete/stats` — Personal knowledge base
+
+---
+
+## 📋 Development Workflow
+
+### When User Asks You to Implement a Feature
+
+**Step 1: Check if Spec exists**
+```
+Look in .kiro/specs/ directory
+```
+
+**Step 2: If Spec exists**
+- Read `requirements.md` - understand what to build
+- Read `design.md` - understand how to build it
+- Read `tasks.md` - see implementation steps
+- Implement according to the Spec
+- Update task status as you complete work
+
+**Step 3: If no Spec exists**
+- Suggest creating a Spec first
+- Help user define requirements
+- Help design the solution
+- Break down into tasks
+- Then implement
+
+### When Working in Multi-Agent Mode
+
+If `.kiro/config/multi-agent.json` exists with `enabled: true`:
+1. Register with AgentRegistry before starting work
+2. Acquire task locks before modifying any task
+3. Use TaskStatusStore for concurrent-safe tasks.md updates
+4. Use SteeringFileLock when updating steering files
+5. Deregister when done (auto-releases all locks)
+
+---
+
+## 📁 Project Structure
+
+```
+.kiro/
+├── README.md                  # This file - project development guide
+├── specs/                     # All Specs live here
+│   └── {spec-name}/           # Individual Spec
+│       ├── requirements.md    # What we're building
+│       ├── design.md          # How we'll build it
+│       ├── tasks.md           # Implementation steps
+│       ├── steering.md        # Spec-level steering (L4, multi-agent)
+│       ├── lifecycle.json     # Spec lifecycle state (multi-agent)
+│       └── locks/             # Task lock files (multi-agent)
+├── steering/                  # Development rules (auto-loaded by AI)
+│   ├── CORE_PRINCIPLES.md     # Core development principles
+│   ├── ENVIRONMENT.md         # Project environment
+│   ├── CURRENT_CONTEXT.md     # Current work context
+│   └── RULES_GUIDE.md         # Rules index
+├── config/                    # Configuration files
+│   ├── multi-agent.json       # Multi-agent coordination config
+│   ├── agent-registry.json    # Active agent registry
+│   └── coordination-log.json  # Coordinator assignment log
+└── tools/                     # Tool configurations
+```
+
+**Key files:**
+- `.kiro/steering/CORE_PRINCIPLES.md` - Development principles for this project
+- `.kiro/steering/CURRENT_CONTEXT.md` - What we're currently working on
+- `.kiro/specs/{spec-name}/` - Feature specifications
+
+---
+
+## 📖 What is a Spec?
+
+A Spec is a complete feature definition with three parts:
+
+### 1. requirements.md - WHAT we're building
+- User stories, functional requirements, acceptance criteria
+
+### 2. design.md - HOW we'll build it
+- Architecture, component design, API design, technology choices
+
+### 3. tasks.md - Implementation steps
+- Ordered task list with dependencies and implementation notes
+- Status: `- [ ]` Not started | `- [-]` In progress | `- [x]` Completed
+
+---
+
+## 💡 Working with This Project
+
+### DO:
+- ✅ Check for existing Specs before starting work
+- ✅ Follow requirements and design in Specs
+- ✅ Update task status as you work
+- ✅ Read steering rules for project-specific guidelines
+- ✅ Use task locks in multi-agent mode
+- ✅ Run tests before marking tasks complete
+
+### DON'T:
+- ❌ Start implementing without understanding requirements
+- ❌ Ignore the design document
+- ❌ Create files in wrong locations (use Spec directories)
+- ❌ Skip updating task status
+- ❌ Modify tasks.md without locks in multi-agent mode
+
+---
+
+## 🔍 Finding Information
+
+| Need | Where |
+|------|-------|
+| Feature requirements | `.kiro/specs/{spec-name}/requirements.md` |
+| Implementation design | `.kiro/specs/{spec-name}/design.md` |
+| What to work on | `.kiro/specs/{spec-name}/tasks.md` |
+| Project context | `.kiro/steering/CURRENT_CONTEXT.md` |
+| Development rules | `.kiro/steering/CORE_PRINCIPLES.md` |
+| Project status | `kse status` |
+| Multi-agent setup | `.kiro/config/multi-agent.json` |
+| Full documentation | `docs/` directory |
+
+---
+
+**Project Type**: Spec-driven development  
+**kse Version**: 1.44.x  
+**Last Updated**: 2026-02-12  
+**Purpose**: Guide AI tools to work effectively with this project

package/template/.kiro/hooks/check-spec-on-create.kiro.hook

@@ -0,0 +1,17 @@
+{
+  "enabled": true,
+  "name": "Check Spec on Create",
+  "description": "Validate spec structure when new spec files are created",
+  "version": "1",
+  "when": {
+    "type": "fileCreated",
+    "patterns": [
+      ".kiro/specs/*/requirements.md",
+      ".kiro/specs/*/design.md"
+    ]
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "A new spec document has been created. Please review it for completeness: check that it has proper structure, clear acceptance criteria, and follows the spec template. Suggest improvements if needed."
+  }
+}

package/template/.kiro/hooks/run-tests-on-save.kiro.hook

@@ -0,0 +1,13 @@
+{
+  "enabled": true,
+  "name": "Run Tests",
+  "description": "Run npm test and report results. Click the button in Agent Hooks panel to trigger.",
+  "version": "1",
+  "when": {
+    "type": "userTriggered"
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "Run `npm test` and if any tests fail, analyze the errors and suggest fixes. If all tests pass, just say the count. Keep it brief."
+  }
+}

package/template/.kiro/hooks/sync-tasks-on-edit.kiro.hook

@@ -0,0 +1,16 @@
+{
+  "enabled": true,
+  "name": "Sync Tasks on Edit",
+  "description": "Automatically sync workspace when tasks.md is edited",
+  "version": "1",
+  "when": {
+    "type": "fileEdited",
+    "patterns": [
+      "**/tasks.md"
+    ]
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "The tasks.md file has been updated. Please review the changes and update the workspace status if needed. Run `kse workspace sync` to synchronize."
+  }
+}