@abarcenas/ai-workflow-template 1.1.0 → 1.13.0

package/README.md

@@ -1,111 +1,248 @@
-# AI Workflow Template
+# 🤖 AI Workflow Template
 
-Publishable AI workflow starter pack for GitHub Copilot. This package distributes the `.github/` experience, auto-bumps versions through Husky, and publishes to npm on merges to `main`.
+**Publishable AI workflow starter pack for GitHub Copilot** - Auto-syncing, version-managed, npm-distributed agent configuration suite.
 
-## What This Package Does
+---
 
-This repository is designed to be installed as an npm package instead of cloned as a one-off template. When a consuming project installs it, the package can copy its `.github/` folder into the consumer project and keep that folder in sync over time.
+## ✨ What This Package Does
 
-### Included capabilities
+This isn't a one-off template to clone—it's a **live npm package** that distributes AI workflow configurations to consumer projects. When installed, it automatically syncs its intelligent agent setup into your project and keeps everything updated over time.
 
-- Copilot instructions and workspace guidance in `.github/co-pilot.instructions.md`
-- Reusable skills in `.github/skills/`
-- Prompt templates in `.github/prompts/`
-- Custom agents in `.github/agents/`
-- Language and framework instructions in `.github/instructions/`
-- Version auto-bumping via Husky pre-commit hook
-- npm publishing workflow on merge to `main`
+### 🎯 Included Capabilities
 
-## Install
+- ⚙️ **27+ Specialized AI Skills** - Reusable, task-based workflows (`.agents/skills/`)
+- 🧠 **Smart Agent Frameworks** - Plan Mode, Implementation Plans, Research Spikes (`.agents/agents/`)
+- 📝 **Framework Instructions** - Technology-specific guidance (`.agents/instructions/`)
+- 💬 **Prompt Templates** - Ready-to-use prompt blueprints (`.agents/prompts/`)
+- 🏃‍♂️ **Caveman Mode** - Ultra-compressed communication for token efficiency
+- 🧪 **Playwright Testing** - Automated testing with MCP integration
+- 📦 **Version Auto-Bumping** - Husky-managed semantic versioning
+- 🚀 **Auto-Publishing** - npm publish on merge to `main`
 
-Install the package in the project that should receive the shared Copilot configuration.
+---
+
+## 🚀 Install
+
+Install directly into the project that needs AI workflow configuration:
 
 ```bash
-npm install ai-workflow-template
+npm install @abarcenas/ai-workflow-template
 ```
 
-If you publish under a scoped name, use that name instead.
+The package runs `postinstall` automatically to sync configurations.
 
-## Sync Behavior
+---
 
-The package runs `scripts/sync.js` during `postinstall`.
+## 🔄 Sync Behavior
 
-- New `.github` files are copied into the consumer project
-- Files that have not been edited locally are refreshed from the package
-- Files that were modified locally are skipped by default
+The sync script runs automatically but offers flexible control:
 
-### Manual sync
-
-Use the sync script directly when you want to refresh the consumer project on demand.
+### 🔧 Manual Sync Options
 
 ```bash
+# Preview changes without applying
+npm run sync -- --dry-run
+
+# Force overwrite local changes
+npm run sync -- --force
+
+# Normal sync
 npm run sync
 ```
 
-Force overwrite of tracked files when you want the package version to win.
+**Smart Sync Rules:**
+- ✅ New files are copied automatically
+- ✅ Unmodified files are refreshed from the package
+- ✅ Locally edited files are preserved (skipped by default)
+- ✅ GitHub Actions workflows are excluded from consumer sync (`.github/workflows/`)
+
+---
+
+## 📚 Core Structure
+
+Post-install, your project receives this organized structure:
+
+```
+.agents/
+├── 📖 instructions/    # 17 instruction sets (frameworks, workflows, security)
+├── 🛠️ skills/         # 27+ specialized AI skills with tools
+├── 🤖 agents/          # 3 agent workflow patterns
+├── 💬 prompts/         # Reusable prompt templates
+└── 📦 compress/        # Token optimization tools
+
+.github/
+└── workflows/          # CI/CD automation (excluded from sync)
+
+docs/
+└── playwright-mcp-configuration.md  # Testing integration guide
+
+AGENTS.md               # Master instruction file with agent guidance
+
+## 🎯 Multi-Agent Orchestrator
+
+The project includes a **multi-agent orchestrator** that dynamically builds and runs development pipelines using specialized sub-agents.
+
+### Agents
+
+| Agent | File | Role |
+|---|---|---|
+| **Orchestrator** | `.opencode/agents/orchestrator.agent.md` | Master — analyzes requests, builds pipelines, delegates |
+| Researcher | `.opencode/agents/researcher.agent.md` | Technical investigation, library evaluation |
+| Architect | `.opencode/agents/architect.agent.md` | System design, component architecture |
+| Implementer | `.opencode/agents/implementer.agent.md` | Translates designs into implementation plans |
+| Designer | `.opencode/agents/designer.agent.md` | UI/UX, styling, responsive design |
+| Coder | `.opencode/agents/coder.agent.md` | Production code implementation |
+| Unit Tester | `.opencode/agents/unit-tester.agent.md` | Unit and integration tests |
+| E2E Tester | `.opencode/agents/e2e-tester.agent.md` | Playwright browser tests |
+| Reviewer | `.opencode/agents/reviewer.agent.md` | Code review, security audit |
+| Deployer | `.opencode/agents/deployer.agent.md` | CI/CD, deployment scripts |
+| Tracker | `.opencode/agents/tracker.agent.md` | Documentation recorder |
+
+### How to Use
+
+Invoke the orchestrator with `@orchestrator` followed by your task:
 
 ```bash
-npm run sync -- --force
+# Full automated pipeline (auto-bootstraps architecture on first run)
+@orchestrator Add a user login feature with email verification
 ```
 
-Preview the sync without writing files.
+```bash
+# Quick execution without step-by-step confirmation
+@orchestrator full pipeline: refactor authentication to use JWT
+```
 
 ```bash
-npm run sync -- --dry-run
+# Specific scope — only the relevant agents run
+@orchestrator fix the pagination bug in the search results component
 ```
 
-## Versioning
+#### What Happens When You Run the Orchestrator
+
+1. **Step 0** — On first run only: auto-detects your project's tech stack, architecture patterns, and layer structure (via the architecture-blueprint-generator skill). Subsequent runs skip this.
+2. **Steps 1-2** — Analyzes your request and builds a pipeline of the relevant sub-agents.
+3. **Steps 3-4** — Executes each agent sequentially; you can confirm or skip each step (or enable auto-confirm for hands-off execution).
+4. **Step 5** — Tracker agent documents everything to `docs/tracker-log.md`.
+5. **Steps 6-7** — Presents results and persists new knowledge so the system gets smarter over time.
 
-Husky runs a pre-commit hook that bumps the package version automatically.
+#### First-Run Behavior
 
-- Normal commits increment the minor version and reset patch to `0`
-- If the major version changes, the script resets the version to `<major>.0.0`
+The very first time you use `@orchestrator` in a project, it automatically runs the architecture-blueprint-generator skill to:
+- Detect your tech stack (frameworks, databases, infrastructure)
+- Identify architectural patterns (Clean Architecture, MVC, etc.)
+- Map layer structure and dependency rules
+- Write the context to `docs/.architecture-context.md` and `.agents/instructions/learned-knowledge.instructions.md`
 
-Example:
+All subsequent runs skip this — agents get architecture context pre-filled.
 
-```text
-1.2.0 -> 1.3.0
-2.0.0 -> 2.1.0 on the next commit
+#### MCP Tooling
+
+Some agents require MCP servers configured in `opencode.mcp.json` (copy from `opencode.mcp.example.json`):
+
+| Agent | Required MCP | Purpose |
+|---|---|---|
+| Researcher | ddg-search, Context7 | Web search + documentation queries |
+| E2E Tester | Playwright | Browser automation |
+| Reviewer | GitHub | PR and issue management |
+| Deployer | GitHub | Releases, Actions |
 ```
 
-## Publish Flow
+**Main Instructions:** `AGENTS.md` - Central guidance for using all features.
 
-GitHub Actions publishes the package to npm when changes are merged into `main`.
+---
 
-### Required secret
+## 🎨 Featured Skills
 
-Add `NPM_TOKEN` in GitHub repository settings:
+### Workflow Automation
+- 🏗️ `architecture-blueprint-generator` - Project analysis & documentation
+- 📋 `create-implementation-plan` - Structured task planning
+- ✍️ `create-readme` - Automated README generation
+- 🎯 `context-map` - File relevance mapping
 
-1. Open your repository on GitHub
-2. Go to Settings
-3. Open Secrets and variables, then Actions
-4. Add a new repository secret named `NPM_TOKEN`
-5. Paste an npm automation token
+### Development Tools
+- 🎭 `playwright-explore-website` / `playwright-generate-test` - Browser automation
+- 🐙 `github-issues` / `gh-cli` - GitHub integration
+- 🧪 `polygot-test-agent` - Multi-language test generation
+- 📚 `microsoft-docs` - Microsoft documentation queries
 
-## Local Development
+### Token & Efficiency Tools
+- 🗣️ `caveman` - Ultra-compressed communication modes
+- 📉 `caveman-compress` / `compress` - Memory file compression
+- 📝 `caveman-commit` - Optimized commit messages
+- 👥 `cavecrew` - Multi-agent coordination
+- 📊 `caveman-stats` - Token usage tracking
 
-Install dependencies once to activate Husky hooks.
+### Quality & Safety
+- 🛡️ `agent-governance` - AI safety controls
+- 🔒 `security-owasp` - OWASP security guidelines
+- 🤝 `conventional-commit` / `git-commit` - Git best practices
 
-```bash
-npm install
-```
+---
+
+## 📦 Versioning
+
+Husky automatically bumps versions on every commit:
+
+- **Minor** version increments by default: `1.2.0 → 1.3.0`
+- **Patch** resets to 0 on each bump
+- **Major** changes reset to `<major>.0.0`
+
+No manual version management required!
+
+---
+
+## 🚀 Publish Flow
+
+GitHub Actions automatically publishes to npm when merging to `main`.
+
+### 🔑 Required Setup
 
-Recommended checks:
+Add `NPM_TOKEN` to GitHub repository secrets:
+
+1. Repository → Settings → Secrets and variables → Actions
+2. New repository secret → Name: `NPM_TOKEN`
+3. Paste npm automation token
+
+**Note:** Publish workflow files (`.github/workflows/`) are excluded from consumer sync to prevent conflicts.
+
+---
+
+## 💻 Local Development
 
 ```bash
+# Install dependencies & activate Husky hooks
+npm install
+
+# Verify sync behavior (dry run)
 npm run sync -- --dry-run
+
+# Test package creation
 npm pack --json
+
+# Run Playwright tests
+npm test
 ```
 
-## Updating the Shared Template
+---
+
+## 🔄 Updating the Shared Template
+
+1. ✏️ Edit files in `.agents/`, `docs/`, or `scripts/`
+2. 🎯 Test changes locally
+3. 💾 Commit (triggers auto-version bump)
+4. 🚀 Merge to `main` (triggers npm publish)
+5. ♻️ Consumers run `npm install` to get updates
+
+---
+
+## 🔔 Important Notes
 
-1. Edit the files in `.github/` that should be distributed to consumer projects
-2. Commit your changes
-3. Merge to `main` to publish the updated package
-4. Consumers can run `npm install` again to pull the latest distributed files
+- ⚙️ Uses `INIT_CWD` to install against consuming project (not package dir)
+- 💾 Local changes are always preserved unless `--force` is used
+- 📖 `AGENTS.md` is the main instruction file agents should read
+- 🎯 Package assumes public npm registry
+- 🎭 Playwright MCP integration documented in `docs/` folder
 
-## Notes
+---
 
-- The sync script uses `INIT_CWD` so installation runs against the consuming project, not the package directory
-- Local changes in a consuming repo are preserved unless you explicitly use `--force`
-- The publish workflow assumes the package is public on npm
+**Happy coding with AI-powered workflows!** 🤖✨

package/opencode.mcp.example.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "ddg-search": {
+       "type": "local",
+       "command": ["npx", "-y", "ddg-mcp-search"],
+       "enabled": true
+     },
+    "github": {
+      "type": "local",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN"
+      },
+      "enabled": true
+    },
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "YOUR_API_KEY"
+      },
+      "enabled": true
+    },
+    "playwright": {
+      "type": "local",
+      "command": "node",
+      "args": ["scripts/mcp/playwright-mcp-launcher.js"],
+      "env": {
+        "HEADLESS": "$HEADLESS",
+        "SLOW_MO": "$SLOW_MO",
+        "VIEWPORT": "$VIEWPORT"
+      },
+      "enabled": true
+    },
+    "example-server": {
+      "type": "local",
+      "command": ["npx", "-y", "your-mcp-package"],
+      "enabled": false
+    },
+    "example-remote": {
+      "type": "remote",
+      "url": "https://your-mcp-server.com/mcp",
+      "enabled": false
+    }
+  },
+  "permission": {
+    "ddg-search_*": "allow",
+    "github_*": "allow",
+    "mcp-everything_*": "allow",
+    "playwright_*": "allow"
+  }
+}

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.1.0",
+  "version": "1.13.0",
   "description": "A comprehensive template repository for AI-assisted development workflows using GitHub Copilot. This template provides a structured approach to leveraging AI assistance through pre-configured skills, prompts, agents, and coding standards.",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "playwright test",
+    "test:headed": "playwright test --headed",
+    "test:ui": "playwright test --ui",
+    "test:debug": "playwright test --debug",
+    "test:report": "playwright show-report",
     "prepare": "husky",
     "sync": "node ./scripts/sync.js",
     "postinstall": "node ./scripts/sync.js"
@@ -22,11 +26,15 @@
   },
   "homepage": "https://github.com/abarcenas29/ai-workflow-template#readme",
   "files": [
-    ".github/",
-    "scripts/"
+    ".agents/",
+    ".github/workflows/",
+    "scripts/",
+    "AGENTS.md",
+    "opencode.mcp.example.json"
   ],
-  "dependencies": {},
   "devDependencies": {
+    "@playwright/test": "^1.59.1",
+    "dotenv": "^17.4.2",
     "husky": "^9.0.0"
   }
 }

package/scripts/mcp/playwright-mcp-launcher.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+/**
+ * Playwright MCP Launcher
+ * This script launches the Playwright MCP server with the correct configuration
+ * based on environment variables and project settings.
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+
+// Get environment variables
+const headless = process.env.HEADLESS === 'true';
+const slowMo = process.env.SLOW_MO ? parseInt(process.env.SLOW_MO) : 0;
+
+// Build command arguments
+const args = ['@playwright/mcp@latest'];
+
+// Add headless flag if needed
+if (headless) {
+  args.push('--headless');
+}
+
+// Add viewport size if specified
+if (process.env.VIEWPORT) {
+  args.push('--viewport', process.env.VIEWPORT);
+}
+
+// Launch the MCP server
+const child = spawn('npx', args, {
+  stdio: 'inherit',
+  shell: true
+});
+
+// Handle process signals
+process.on('SIGINT', () => {
+  child.kill('SIGINT');
+});
+
+process.on('SIGTERM', () => {
+  child.kill('SIGTERM');
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});

package/scripts/sync.js

@@ -5,10 +5,11 @@ import { fileURLToPath } from 'url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const packageRoot = resolve(__dirname, '..')
-const sourceGithubDir = resolve(packageRoot, '.github')
+const sourceAgentsDir = resolve(packageRoot, '.agents')
 const consumerRoot = process.env.INIT_CWD ? resolve(process.env.INIT_CWD) : process.cwd()
-const targetGithubDir = resolve(consumerRoot, '.github')
-const manifestPath = resolve(consumerRoot, '.github-sync-manifest.json')
+const targetAgentsDir = resolve(consumerRoot, '.agents')
+const manifestPath = resolve(consumerRoot, '.agents-sync-manifest.json')
+const excludedRelativePaths = new Set([])
 const args = new Set(process.argv.slice(2))
 const forceOverwrite = args.has('--force')
 const dryRun = args.has('--dry-run')
@@ -75,27 +76,36 @@ function syncFile(sourceFile, targetFile) {
   copyFileSync(sourceFile, targetFile)
 }
 
-if (!existsSync(sourceGithubDir)) {
-  console.warn('[ai-workflow-template] No .github directory found to sync.')
+const rootFiles = ['AGENTS.md', 'opencode.mcp.example.json']
+
+if (!existsSync(sourceAgentsDir)) {
+  console.warn('[ai-workflow-template] No .agents directory found to sync.')
   process.exit(0)
 }
 
 const manifest = readManifest()
-const sourceFiles = collectFiles(sourceGithubDir)
+const sourceFiles = collectFiles(sourceAgentsDir)
 let copied = 0
 let skipped = 0
 let added = 0
 
+/* ──  Sync .agents/ directory ────────────────────────────────── */
+
 for (const sourceFile of sourceFiles) {
-  const relativePath = relative(sourceGithubDir, sourceFile)
-  const targetFile = resolve(targetGithubDir, relativePath)
+  const relativePath = relative(sourceAgentsDir, sourceFile)
+  if (excludedRelativePaths.has(relativePath)) {
+    continue
+  }
+
+  const targetFile = resolve(targetAgentsDir, relativePath)
   const sourceHash = hashFile(sourceFile)
   const existingHash = existsSync(targetFile) ? hashFile(targetFile) : null
-  const recordedHash = manifest.files[relativePath] ?? null
+  const trackedKey = relativePath
+  const recordedHash = manifest.files[trackedKey] ?? null
 
   if (!existsSync(targetFile)) {
     syncFile(sourceFile, targetFile)
-    manifest.files[relativePath] = sourceHash
+    manifest.files[trackedKey] = sourceHash
     copied += 1
     added += 1
     continue
@@ -105,7 +115,7 @@ for (const sourceFile of sourceFiles) {
 
   if (forceOverwrite || isUntouched) {
     syncFile(sourceFile, targetFile)
-    manifest.files[relativePath] = sourceHash
+    manifest.files[trackedKey] = sourceHash
     copied += 1
     continue
   }
@@ -114,6 +124,39 @@ for (const sourceFile of sourceFiles) {
   console.warn(`[ai-workflow-template] Skipped locally modified file: ${relativePath}`)
 }
 
+for (const rootFile of rootFiles) {
+  const sourceFile = resolve(packageRoot, rootFile)
+  if (!existsSync(sourceFile)) {
+    continue
+  }
+
+  const targetFile = resolve(consumerRoot, rootFile)
+  const sourceHash = hashFile(sourceFile)
+  const existingHash = existsSync(targetFile) ? hashFile(targetFile) : null
+  const trackedKey = `__root__/${rootFile}`
+  const recordedHash = manifest.files[trackedKey] ?? null
+
+  if (!existsSync(targetFile)) {
+    syncFile(sourceFile, targetFile)
+    manifest.files[trackedKey] = sourceHash
+    copied += 1
+    added += 1
+    continue
+  }
+
+  const isUntouched = recordedHash !== null && existingHash === recordedHash
+
+  if (forceOverwrite || isUntouched) {
+    syncFile(sourceFile, targetFile)
+    manifest.files[trackedKey] = sourceHash
+    copied += 1
+    continue
+  }
+
+  skipped += 1
+  console.warn(`[ai-workflow-template] Skipped locally modified root file: ${rootFile}`)
+}
+
 if (!dryRun) {
   writeManifest(manifest)
 }