@abarcenas/ai-workflow-template 1.2.0 → 1.13.0

package/AGENTS.md

@@ -0,0 +1,149 @@
+# opencode Agent Instructions
+
+## Project Context
+
+This project includes AI-assisted development configuration distributed through the `ai-workflow-template` package. The key directories are:
+
+- `.agents/instructions/` — Language, framework, and workflow instructions
+- `.agents/skills/` — Reusable skill definitions for task-based workflows
+- `.agents/agents/` — Specialized agent definitions for planning, research, and implementation
+- `.agents/prompts/` — Reusable prompt templates
+
+## Core Workflow
+
+1. **Understand before acting** — Read relevant instructions from `.agents/instructions/` before working with specific technologies
+2. **Plan before implementing** — Use `.agents/agents/plan.agent.md` or `.agents/agents/implementation-plan.agent.md` patterns for structured work
+3. **Track progress** — Update `.copilot-tracking/changes/*.md` after each task (see `.agents/instructions/task-implementation.instructions.md`)
+4. **Maintain context** — Keep memory bank files updated (see `.agents/instructions/memory-bank.instructions.md`)
+
+## Instructions Reference
+
+| Scope | File |
+|---|---|
+| All work | `.agents/instructions/memory-bank.instructions.md` |
+| Task implementation | `.agents/instructions/task-implementation.instructions.md` |
+| TypeScript | `.agents/instructions/typescript.instructions.md` |
+| Node.js / Vitest | `.agents/instructions/nodejs-vitest.instructions.md` |
+| Shell scripts | `.agents/instructions/shell.instructions.md` |
+| Go | `.agents/instructions/go.instructions.md` |
+| Angular | `.agents/instructions/angular.instructions.md` |
+| Markdown docs | `.agents/instructions/markdown.instructions.md` |
+| Prompts | `.agents/instructions/prompt.instructions.md` |
+| Agent files | `.agents/instructions/agent.instructions.md` |
+| Agent skills | `.agents/instructions/agent-skill.instructions.md` |
+| Security | `.agents/instructions/security-owasp.instructions.md` |
+| Playwright tests | `.agents/instructions/playwright-typescript.instructions.md` |
+| Instructions files | `.agents/instructions/instructions.instructions.md` |
+| Agent safety | `.agents/instructions/agent-safety.instructions.md` |
+| AI safety | `.agents/instructions/ai-prompt-engineering-safety.instructions.md` |
+| Context7 | `.agents/instructions/context7.instructions.md` |
+| HTML/CSS styling | `.agents/instructions/html-to-css-guide.instructions.md` |
+
+## Available Skills
+
+Skills in `.agents/skills/` provide structured workflows for common tasks. Load them when the task matches the skill's purpose:
+
+- `architecture-blueprint-generator` — Generate project architecture blueprints
+- `conventional-commit` — Create conventional commit messages
+- `create-implementation-plan` — Create structured implementation plans
+- `create-readme` — Generate README files
+- `create-specification` — Create specification files for GenAI consumption
+- `context-map` — Map relevant files before making changes
+- `editorconfig` — Generate .editorconfig files
+- `git-commit` — Execute safe git commits
+- `github-issues` — Manage GitHub issues via MCP
+- `microsoft-docs` — Query Microsoft documentation
+- `playwright-explore-website` — Explore websites with Playwright
+- `playwright-generate-test` — Generate Playwright tests
+- `polygot-test-agent` — Multi-agent polyglot test generation
+- `prompt-builder` — Build high-quality prompts
+- `agent-governance` — Add governance and safety to agent systems
+- `boost-prompt` — Iteratively refine prompts
+- `chrome-devtools` — Browser automation via Chrome DevTools MCP
+- `gh-cli` — GitHub CLI reference
+- `caveman` — Ultra-compressed communication mode
+- `caveman-commit` — Compressed commit message generator
+- `caveman-compress` — Token compression tool
+- `caveman-help` — Help system for caveman skills
+- `caveman-review` — Automated code review
+- `caveman-stats` — Tracking and statistics for caveman usage
+- `cavecrew` — Multi-agent coordination for caveman skills
+- `compress` — General compression utilities
+
+## Available Prompts
+
+Prompts in `.agents/prompts/` can be invoked directly:
+
+- `editconfig` — Generate .editorconfig
+- `playwright-explore` — Explore a website
+- `playwright-generate-test` — Generate Playwright tests
+- `documentation-writer` — Write documentation (Diataxis framework)
+
+## Available Agent Workflows
+
+These agent workflows (from `.agents/agents/`) define specialized modes of operation. Invoke the relevant workflow at the start of a task by stating which mode you want to activate.
+
+### Plan Mode — Strategic Planning & Architecture
+
+Use this when starting a new feature, refactoring, or any non-trivial change. Follow this sequence:
+
+1. **Understand the Goal** — Ask clarifying questions about requirements and goals
+2. **Explore Context** — Examine relevant files, components, and systems that will be affected
+3. **Identify Constraints** — Determine technical limitations, dependencies, and requirements
+4. **Clarify Scope** — Establish how extensive the changes should be
+5. **Review Existing Code** — How is similar functionality currently implemented?
+6. **Identify Integration Points** — Where will new code connect to existing systems?
+7. **Plan Step-by-Step** — Create a logical sequence for implementation
+8. **Consider Testing** — How can the implementation be validated?
+9. **Present Clear Plans** — Provide detailed strategy with reasoning, file paths, and order
+
+Always prioritize understanding and planning over immediate implementation. Break down complex requirements into manageable components. Propose multiple approaches with trade-offs when viable alternatives exist.
+
+### Implementation Plan Generation
+
+Use this to create deterministic, structured plans saved to `/plan/`. Follow this template:
+
+- Save files as `/plan/[purpose]-[component]-[version].md`
+- Purpose prefixes: `upgrade|refactor|feature|data|infrastructure|process|architecture|design`
+- **Required front matter**: `goal`, `version`, `date_created`, `status` (Completed/In progress/Planned/Deprecated/On Hold), `tags`
+- **Required sections** (in order):
+  1. Introduction (with status badge)
+  2. Requirements & Constraints (with REQ-, SEC-, CON- identifiers)
+  3. Implementation Steps (phases with task tables: Task ID, Description, Completed, Date)
+  4. Alternatives (ALT- identifiers with rationale)
+  5. Dependencies (DEP- identifiers)
+  6. Files (FILE- identifiers)
+  7. Testing (TEST- identifiers)
+  8. Risks & Assumptions (RISK-, ASSUMPTION- identifiers)
+  9. Related Specifications
+
+Plans must be deterministic, self-contained, and immediately actionable. Use unambiguous language, specific file paths, and explicit completion criteria per task. DO NOT make code edits — only generate the plan.
+
+### Research Spike — Systematic Technical Investigation
+
+Use this when investigating technical unknowns, evaluating libraries, or validating approaches. Follow this process:
+
+1. **Parse Spike** — Read and understand the spike document; identify all research questions and success criteria
+2. **Investigate Exhaustively** — Research official docs, search for code examples, examine real implementations, explore edge cases
+3. **Recursive Research** — For every new term/concept discovered, immediately investigate it; continue until no new relevant information emerges
+4. **Cross-Reference** — Validate findings across multiple sources; document both successes AND dead ends
+5. **Experimental Validation** — Ask permission before creating files or running commands; design minimal proof-of-concept tests
+6. **Continuous Documentation** — Update the spike document continuously as discoveries are made (not just at the end)
+7. **Evidence Standards** — Cite specific sources with URLs and versions; include timestamps; note limitations
+
+Always ask user permission before: creating files, running commands, modifying the system, or experimental operations.
+
+### Feature Pipeline — Stripped-Down Sequential Pipeline
+
+Use this when you want a fixed, opinionated pipeline: **implementer → designer → coder → tracker**. It bootstraps architecture context, supports step-by-step confirmation, logs progress, and persists lessons learned.
+
+The agent file is at `.opencode/agents/orchestrator/feature-pipeline.agent.md`.
+
+**When to use:** You want a predictable, four-step feature pipeline without dynamic agent selection. The orchestrator agent is more flexible; this is more opinionated.
+
+## Additional Resources
+
+### Playwright MCP Configuration
+
+For details on how Playwright MCP integrates with the headed mode debugging configuration, see:
+- **Docs**: `docs/playwright-mcp-configuration.md`

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.2.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);
+});