ai-eng-system 0.0.11 → 0.0.12

package/README.md

@@ -4,6 +4,31 @@ Advanced development tools with context engineering, research orchestration, and
 
 ## 🚀 Quick Start
 
+### Spec-Driven Development (Recommended)
+
+This toolkit follows the **spec-driven development methodology** from GitHub's official blog post: [Spec-driven development with AI: Get started with a new open source toolkit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/).
+
+**The 5-Phase Workflow** (always in this order):
+
+```mermaid
+flowchart LR
+    A[🎯 Research] --> B[📋 Specify] --> C[📝 Plan] --> D[🔨 Work] --> E[🔍 Review]
+    D -.->|If changes needed| E
+    E -.->|Repeat| D
+```
+
+| Phase | Command | Output |
+|-------|---------|--------|
+| 1. Research | `/ai-eng/research` | Context and findings |
+| 2. Specify | `/ai-eng/specify` | Feature specification |
+| 3. Plan | `/ai-eng/plan` | Implementation plan |
+| 4. Work | `/ai-eng/work` | Quality-gated code |
+| 5. Review | `/ai-eng/review` | Multi-agent approval |
+
+This approach ensures specifications are your "source of truth" for what gets built, reducing guesswork and enabling more reliable AI-assisted development.
+
+See [docs/spec-driven-workflow.md](./docs/spec-driven-workflow.md) for complete workflow guide with examples.
+
 ### Claude Code (Recommended)
 ```bash
 /plugin marketplace add v1truv1us/ai-eng-system
@@ -22,11 +47,21 @@ Advanced development tools with context engineering, research orchestration, and
 ```
 ## 📋 What's Included
 
-### Commands (16 total)
-- `/ai-eng/plan` - Create detailed implementation plans
-- `/ai-eng/review` - Multi-perspective code review (29 agents)
-- `/ai-eng/seo` - SEO audits with Core Web Vitals
-- `/ai-eng/work` - Execute plans with quality gates
+### Spec-Driven Development Workflow
+
+**Core workflow for systematic development** (always research → specify → plan → work → review):
+
+| Phase | Command | Purpose |
+|-------|---------|---------|
+| 1. Research | `/ai-eng/research` | Multi-phase research with codebase and external context |
+| 2. Specify | `/ai-eng/specify` | Create feature specifications with TCRO framework |
+| 3. Plan | `/ai-eng/plan` | Create detailed implementation plans from specs |
+| 4. Work | `/ai-eng/work` | Execute plans with quality gates and validation |
+| 5. Review | `/ai-eng/review` | Multi-perspective code review (29 agents) |
+
+> **Methodology**: Based on [GitHub's spec-driven development approach](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)
+
+### Additional Commands (12 total)
 - `/ai-eng/optimize` - Prompt enhancement (+45% quality)
 - `/ai-eng/deploy` - Pre-deployment checklists
 - `/ai-eng/compound` - Document solved problems
@@ -36,9 +71,11 @@ Advanced development tools with context engineering, research orchestration, and
 - `/ai-eng/create-command` - AI-assisted command generation
 - `/ai-eng/create-skill` - AI-assisted skill creation
 - `/ai-eng/create-tool` - AI-assisted custom tool creation
-- `/ai-eng/research` - Multi-phase research orchestration
 - `/ai-eng/context` - Context management and retrieval
 - `/ai-eng/clean` - Remove build artifacts and generated files
+- `/ai-eng/seo` - SEO audits with Core Web Vitals
+
+**Total Commands**: 17
 
 ### Agents (29 total)
 - **Architecture & Planning**: `architect-advisor`, `backend-architect`, `infrastructure-builder`
@@ -163,4 +200,10 @@ Commands reference specialized agents automatically:
 /ai-eng/review --agent=backend-architect  # Architecture review
 ```
 
-**Built with research-backed prompting techniques** (+45-115% quality improvement)
+**Built with research-backed prompting techniques** (+45-115% quality improvement)
+
+## 📖 Workflow Guide
+
+For complete documentation on the **Research → Specify → Plan → Work → Review** workflow, see:
+- **[docs/spec-driven-workflow.md](./docs/spec-driven-workflow.md)** - Visual workflow guide with examples
+- **[docs/research-command-guide.md](./docs/research-command-guide.md)** - Research command deep dive

package/dist/.claude-plugin/commands/research.md

@@ -33,6 +33,9 @@ outputs:
 
 Conduct comprehensive research for: $ARGUMENTS
 
+> **Phase 1 of Spec-Driven Workflow**: Research → Specify → Plan → Work → Review  
+> See: [GitHub's spec-driven development methodology](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)
+
 ## Usage
 
 ```bash

package/dist/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-eng-system",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "AI Engineering System with context engineering and research orchestration for Claude Code",
   "author": "v1truv1us",
   "license": "MIT",

package/dist/.claude-plugin/skills/AGENTS.md

@@ -7,31 +7,80 @@
 Modular, reusable skill definitions that support the agents defined in the parent AGENTS.md.
 
 ## Project Overview
-Modular skill definitions for DevOps and prompting capabilities.
+
+Flat directory structure of skill definitions for Claude Code and OpenCode. Each skill is self-contained in its own directory with a `SKILL.md` file and optional supporting files.
 
 ## Directory Structure
-- `devops/` - DevOps automation skills
-  - `coolify-deploy/` - Coolify deployment best practices
-  - `git-worktree/` - Git worktree workflows
-- `prompting/` - Prompt enhancement techniques
-  - `incentive-prompting/` - Research-backed prompting methods
+
+```
+skills/
+├── comprehensive-research/   # Multi-phase research orchestration
+│   └── SKILL.md
+├── coolify-deploy/           # Coolify deployment best practices
+│   └── SKILL.md
+├── git-worktree/             # Git worktree workflows
+│   └── SKILL.md
+├── incentive-prompting/      # Research-backed prompting techniques
+│   └── SKILL.md
+├── plugin-dev/               # Plugin development knowledge base
+│   ├── SKILL.md
+│   └── references/           # Supporting documentation
+├── prompt-refinement/        # TCRO prompt structuring
+│   ├── SKILL.md
+│   └── templates/            # Phase-specific templates
+├── text-cleanup/             # AI verbosity removal patterns
+│   ├── SKILL.md
+│   └── patterns/             # Pattern definitions
+└── AGENTS.md                 # This file
+```
+
+## Skill Format
+
+Each skill follows the Claude Code/OpenCode skill format:
+
+```markdown
+---
+name: skill-name
+description: Brief description for semantic matching. Include trigger words.
+---
+
+# Skill Name
+
+[Skill instructions and content]
+```
+
+## Available Skills
+
+| Skill | Description | Invoked By |
+|-------|-------------|------------|
+| `prompt-refinement` | Transform prompts into structured TCRO format | `/ai-eng/research`, `/ai-eng/plan`, `/ai-eng/work`, `/ai-eng/specify` |
+| `incentive-prompting` | Research-backed prompting techniques (+45-115% quality) | `/ai-eng/optimize`, agent enhancement |
+| `comprehensive-research` | Multi-phase research orchestration | `/ai-eng/research` |
+| `text-cleanup` | Remove AI-generated verbosity and slop | `/ai-eng/clean` |
+| `coolify-deploy` | Coolify deployment best practices | `/ai-eng/deploy` |
+| `git-worktree` | Git worktree workflow management | `/ai-eng/work` (large features) |
+| `plugin-dev` | Plugin development for Claude Code/OpenCode | `/ai-eng/create-*` commands |
+
+## Skill Loading Mechanism
+
+Skills are loaded via the native `skill` tool in Claude Code and OpenCode:
+
+1. **Discovery**: At startup, skill names and descriptions are indexed
+2. **Activation**: When a request matches a skill's description, the agent invokes `skill({ name: "skill-name" })`
+3. **Loading**: Full `SKILL.md` content is loaded into context
+4. **Execution**: Agent follows the skill's instructions
 
 ## Code Style
-- Each skill has dedicated `SKILL.md` with frontmatter
-- Use YAML frontmatter for metadata (name, description)
+
+- Each skill has dedicated `SKILL.md` with YAML frontmatter
+- Use descriptive `description` field with trigger words for semantic matching
 - Keep skill descriptions concise and actionable
 - Include practical examples and usage patterns
-
-## Key Skills
-**DevOps:**
-- Coolify deployment automation
-- Git worktree management
-
-**Prompting:**
-- Incentive-based prompting techniques
-- Research-backed optimization methods
+- Supporting files go in subdirectories (e.g., `templates/`, `patterns/`, `references/`)
 
 ## Integration Notes
+
 - Skills integrate with parent AGENTS.md coordination system
 - Must maintain compatibility with command implementations
-- Each skill should be self-contained and reusable
+- Each skill should be self-contained and reusable
+- Skills are synced to `.claude/skills/` and `.opencode/skill/` during build

package/dist/.claude-plugin/skills/{research/comprehensive-research → comprehensive-research}/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comprehensive-research
-description: Multi-phase research orchestration skill for thorough codebase, documentation, and external knowledge investigation
+description: Multi-phase research orchestration for thorough codebase, documentation, and external knowledge investigation. Invoked by /ai-eng/research command. Use when conducting deep analysis, exploring codebases, investigating patterns, or synthesizing findings from multiple sources.
 version: 1.0.0
 tags: [research, analysis, discovery, documentation, synthesis, multi-agent]
 ---

package/dist/{skills/prompting → .claude-plugin/skills}/incentive-prompting/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: incentive-prompting
-description: Research-backed prompting techniques for improved AI response quality
+description: Research-backed prompting techniques for improved AI response quality (+45-115% improvement). Use when optimizing prompts, enhancing agent instructions, or when maximum response quality is critical. Invoked by /ai-eng/optimize command. Includes expert persona, stakes language, step-by-step reasoning, challenge framing, and self-evaluation techniques.
 version: 1.0.0
-tags: [prompting, optimization, ai-enhancement]
+tags: [prompting, optimization, ai-enhancement, quality]
 ---
 
 # Incentive-Based Prompting Skill

package/dist/{skills/prompting → .claude-plugin/skills}/prompt-refinement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prompt-refinement
-description: Transform vague prompts into structured TCRO specifications with phase-specific clarification
+description: Transform prompts into structured TCRO format with phase-specific clarification. Automatically invoked by /ai-eng/research, /ai-eng/plan, /ai-eng/work, and /ai-eng/specify commands. Use when refining vague prompts, structuring requirements, or enhancing user input quality before execution.
 version: 1.0.0
 tags: [prompting, clarification, structuring, tcro]
 ---
@@ -141,7 +141,7 @@ Phase: [research|specify|plan|work]
 Phase-specific templates are located in `templates/`:
 
 ```
-skills/prompting/prompt-refinement/
+skills/prompt-refinement/
 ├── SKILL.md
 └── templates/
     ├── research.md

package/dist/.opencode/command/ai-eng/research.md

@@ -33,6 +33,9 @@ outputs:
 
 Conduct comprehensive research for: $ARGUMENTS
 
+> **Phase 1 of Spec-Driven Workflow**: Research → Specify → Plan → Work → Review  
+> See: [GitHub's spec-driven development methodology](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)
+
 ## Usage
 
 ```bash

package/dist/.opencode/skill/comprehensive-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comprehensive-research
-description: Multi-phase research orchestration skill for thorough codebase, documentation, and external knowledge investigation
+description: Multi-phase research orchestration for thorough codebase, documentation, and external knowledge investigation. Invoked by /ai-eng/research command. Use when conducting deep analysis, exploring codebases, investigating patterns, or synthesizing findings from multiple sources.
 version: 1.0.0
 tags: [research, analysis, discovery, documentation, synthesis, multi-agent]
 ---

package/dist/.opencode/skill/incentive-prompting/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: incentive-prompting
-description: Research-backed prompting techniques for improved AI response quality
+description: Research-backed prompting techniques for improved AI response quality (+45-115% improvement). Use when optimizing prompts, enhancing agent instructions, or when maximum response quality is critical. Invoked by /ai-eng/optimize command. Includes expert persona, stakes language, step-by-step reasoning, challenge framing, and self-evaluation techniques.
 version: 1.0.0
-tags: [prompting, optimization, ai-enhancement]
+tags: [prompting, optimization, ai-enhancement, quality]
 ---
 
 # Incentive-Based Prompting Skill

package/dist/.opencode/skill/prompt-refinement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prompt-refinement
-description: Transform vague prompts into structured TCRO specifications with phase-specific clarification
+description: Transform prompts into structured TCRO format with phase-specific clarification. Automatically invoked by /ai-eng/research, /ai-eng/plan, /ai-eng/work, and /ai-eng/specify commands. Use when refining vague prompts, structuring requirements, or enhancing user input quality before execution.
 version: 1.0.0
 tags: [prompting, clarification, structuring, tcro]
 ---
@@ -141,7 +141,7 @@ Phase: [research|specify|plan|work]
 Phase-specific templates are located in `templates/`:
 
 ```
-skills/prompting/prompt-refinement/
+skills/prompt-refinement/
 ├── SKILL.md
 └── templates/
     ├── research.md

package/dist/index.js

@@ -1,6 +1,41 @@
 // src/index.ts
 import fs from "node:fs";
 import path from "node:path";
+
+// src/types/common.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringRecord(value) {
+  if (!isRecord(value))
+    return false;
+  return Object.values(value).every((v) => typeof v === "string");
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function hasProperty(obj, key) {
+  return isRecord(obj) && key in obj;
+}
+function isArray(value) {
+  return Array.isArray(value);
+}
+function isString(value) {
+  return typeof value === "string";
+}
+function isNumber(value) {
+  return typeof value === "number" && !Number.isNaN(value);
+}
+function isBoolean(value) {
+  return typeof value === "boolean";
+}
+function getProperty(obj, key, defaultValue) {
+  if (!isRecord(obj))
+    return defaultValue;
+  return key in obj ? obj[key] : defaultValue;
+}
+
+// src/index.ts
 function copyRecursive(src, dest) {
   const stat = fs.statSync(src);
   if (stat.isDirectory()) {
@@ -47,5 +82,14 @@ var AiEngSystem = async ({ directory }) => {
   return {};
 };
 export {
+  isStringRecord,
+  isString,
+  isRecord,
+  isObject,
+  isNumber,
+  isBoolean,
+  isArray,
+  hasProperty,
+  getProperty,
   AiEngSystem
 };

package/dist/skills/AGENTS.md

@@ -7,31 +7,80 @@
 Modular, reusable skill definitions that support the agents defined in the parent AGENTS.md.
 
 ## Project Overview
-Modular skill definitions for DevOps and prompting capabilities.
+
+Flat directory structure of skill definitions for Claude Code and OpenCode. Each skill is self-contained in its own directory with a `SKILL.md` file and optional supporting files.
 
 ## Directory Structure
-- `devops/` - DevOps automation skills
-  - `coolify-deploy/` - Coolify deployment best practices
-  - `git-worktree/` - Git worktree workflows
-- `prompting/` - Prompt enhancement techniques
-  - `incentive-prompting/` - Research-backed prompting methods
+
+```
+skills/
+├── comprehensive-research/   # Multi-phase research orchestration
+│   └── SKILL.md
+├── coolify-deploy/           # Coolify deployment best practices
+│   └── SKILL.md
+├── git-worktree/             # Git worktree workflows
+│   └── SKILL.md
+├── incentive-prompting/      # Research-backed prompting techniques
+│   └── SKILL.md
+├── plugin-dev/               # Plugin development knowledge base
+│   ├── SKILL.md
+│   └── references/           # Supporting documentation
+├── prompt-refinement/        # TCRO prompt structuring
+│   ├── SKILL.md
+│   └── templates/            # Phase-specific templates
+├── text-cleanup/             # AI verbosity removal patterns
+│   ├── SKILL.md
+│   └── patterns/             # Pattern definitions
+└── AGENTS.md                 # This file
+```
+
+## Skill Format
+
+Each skill follows the Claude Code/OpenCode skill format:
+
+```markdown
+---
+name: skill-name
+description: Brief description for semantic matching. Include trigger words.
+---
+
+# Skill Name
+
+[Skill instructions and content]
+```
+
+## Available Skills
+
+| Skill | Description | Invoked By |
+|-------|-------------|------------|
+| `prompt-refinement` | Transform prompts into structured TCRO format | `/ai-eng/research`, `/ai-eng/plan`, `/ai-eng/work`, `/ai-eng/specify` |
+| `incentive-prompting` | Research-backed prompting techniques (+45-115% quality) | `/ai-eng/optimize`, agent enhancement |
+| `comprehensive-research` | Multi-phase research orchestration | `/ai-eng/research` |
+| `text-cleanup` | Remove AI-generated verbosity and slop | `/ai-eng/clean` |
+| `coolify-deploy` | Coolify deployment best practices | `/ai-eng/deploy` |
+| `git-worktree` | Git worktree workflow management | `/ai-eng/work` (large features) |
+| `plugin-dev` | Plugin development for Claude Code/OpenCode | `/ai-eng/create-*` commands |
+
+## Skill Loading Mechanism
+
+Skills are loaded via the native `skill` tool in Claude Code and OpenCode:
+
+1. **Discovery**: At startup, skill names and descriptions are indexed
+2. **Activation**: When a request matches a skill's description, the agent invokes `skill({ name: "skill-name" })`
+3. **Loading**: Full `SKILL.md` content is loaded into context
+4. **Execution**: Agent follows the skill's instructions
 
 ## Code Style
-- Each skill has dedicated `SKILL.md` with frontmatter
-- Use YAML frontmatter for metadata (name, description)
+
+- Each skill has dedicated `SKILL.md` with YAML frontmatter
+- Use descriptive `description` field with trigger words for semantic matching
 - Keep skill descriptions concise and actionable
 - Include practical examples and usage patterns
-
-## Key Skills
-**DevOps:**
-- Coolify deployment automation
-- Git worktree management
-
-**Prompting:**
-- Incentive-based prompting techniques
-- Research-backed optimization methods
+- Supporting files go in subdirectories (e.g., `templates/`, `patterns/`, `references/`)
 
 ## Integration Notes
+
 - Skills integrate with parent AGENTS.md coordination system
 - Must maintain compatibility with command implementations
-- Each skill should be self-contained and reusable
+- Each skill should be self-contained and reusable
+- Skills are synced to `.claude/skills/` and `.opencode/skill/` during build

package/dist/skills/{research/comprehensive-research → comprehensive-research}/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comprehensive-research
-description: Multi-phase research orchestration skill for thorough codebase, documentation, and external knowledge investigation
+description: Multi-phase research orchestration for thorough codebase, documentation, and external knowledge investigation. Invoked by /ai-eng/research command. Use when conducting deep analysis, exploring codebases, investigating patterns, or synthesizing findings from multiple sources.
 version: 1.0.0
 tags: [research, analysis, discovery, documentation, synthesis, multi-agent]
 ---

package/dist/{.claude-plugin/skills/prompting → skills}/incentive-prompting/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: incentive-prompting
-description: Research-backed prompting techniques for improved AI response quality
+description: Research-backed prompting techniques for improved AI response quality (+45-115% improvement). Use when optimizing prompts, enhancing agent instructions, or when maximum response quality is critical. Invoked by /ai-eng/optimize command. Includes expert persona, stakes language, step-by-step reasoning, challenge framing, and self-evaluation techniques.
 version: 1.0.0
-tags: [prompting, optimization, ai-enhancement]
+tags: [prompting, optimization, ai-enhancement, quality]
 ---
 
 # Incentive-Based Prompting Skill

package/dist/{.claude-plugin/skills/prompting → skills}/prompt-refinement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prompt-refinement
-description: Transform vague prompts into structured TCRO specifications with phase-specific clarification
+description: Transform prompts into structured TCRO format with phase-specific clarification. Automatically invoked by /ai-eng/research, /ai-eng/plan, /ai-eng/work, and /ai-eng/specify commands. Use when refining vague prompts, structuring requirements, or enhancing user input quality before execution.
 version: 1.0.0
 tags: [prompting, clarification, structuring, tcro]
 ---
@@ -141,7 +141,7 @@ Phase: [research|specify|plan|work]
 Phase-specific templates are located in `templates/`:
 
 ```
-skills/prompting/prompt-refinement/
+skills/prompt-refinement/
 ├── SKILL.md
 └── templates/
     ├── research.md

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ai-eng-system",
-    "version": "0.0.11",
+    "version": "0.0.12",
     "description": "Compounding engineering system for Claude Code and OpenCode. Shared agents, commands, skills, and plugin development tools.",
     "type": "module",
     "main": "./dist/index.js",