@abarcenas/ai-workflow-template 1.1.0 → 1.13.0

package/.agents/skills/compress/scripts/validate.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+import re
+from collections import Counter
+from pathlib import Path
+
+URL_REGEX = re.compile(r"https?://[^\s)]+")
+FENCE_OPEN_REGEX = re.compile(r"^(\s{0,3})(`{3,}|~{3,})(.*)$")
+HEADING_REGEX = re.compile(r"^(#{1,6})\s+(.*)", re.MULTILINE)
+BULLET_REGEX = re.compile(r"^\s*[-*+]\s+", re.MULTILINE)
+
+# crude but effective path detection
+# Requires either a path prefix (./ ../ / or drive letter) or a slash/backslash within the match
+PATH_REGEX = re.compile(r"(?:\./|\.\./|/|[A-Za-z]:\\)[\w\-/\\\.]+|[\w\-\.]+[/\\][\w\-/\\\.]+")
+
+
+class ValidationResult:
+    def __init__(self):
+        self.is_valid = True
+        self.errors = []
+        self.warnings = []
+
+    def add_error(self, msg):
+        self.is_valid = False
+        self.errors.append(msg)
+
+    def add_warning(self, msg):
+        self.warnings.append(msg)
+
+
+def read_file(path: Path) -> str:
+    return path.read_text(errors="ignore")
+
+
+# ---------- Extractors ----------
+
+
+def extract_headings(text):
+    return [(level, title.strip()) for level, title in HEADING_REGEX.findall(text)]
+
+
+def extract_code_blocks(text):
+    """Line-based fenced code block extractor.
+
+    Handles ``` and ~~~ fences with variable length (CommonMark: closing
+    fence must use same char and be at least as long as opening). Supports
+    nested fences (e.g. an outer 4-backtick block wrapping inner 3-backtick
+    content).
+    """
+    blocks = []
+    lines = text.split("\n")
+    i = 0
+    n = len(lines)
+    while i < n:
+        m = FENCE_OPEN_REGEX.match(lines[i])
+        if not m:
+            i += 1
+            continue
+        fence_char = m.group(2)[0]
+        fence_len = len(m.group(2))
+        open_line = lines[i]
+        block_lines = [open_line]
+        i += 1
+        closed = False
+        while i < n:
+            close_m = FENCE_OPEN_REGEX.match(lines[i])
+            if (
+                close_m
+                and close_m.group(2)[0] == fence_char
+                and len(close_m.group(2)) >= fence_len
+                and close_m.group(3).strip() == ""
+            ):
+                block_lines.append(lines[i])
+                closed = True
+                i += 1
+                break
+            block_lines.append(lines[i])
+            i += 1
+        if closed:
+            blocks.append("\n".join(block_lines))
+        # Unclosed fences are silently skipped — they indicate malformed markdown
+        # and including them would cause false-positive validation failures.
+    return blocks
+
+
+def extract_urls(text):
+    return set(URL_REGEX.findall(text))
+
+
+def extract_paths(text):
+    return set(PATH_REGEX.findall(text))
+
+
+def count_bullets(text):
+    return len(BULLET_REGEX.findall(text))
+
+
+def extract_inline_codes(text):
+    text_without_fences = re.sub(r"^```[\s\S]*?^```", "", text, flags=re.MULTILINE)
+    text_without_fences = re.sub(r"^~~~[\s\S]*?^~~~", "", text_without_fences, flags=re.MULTILINE)
+    return re.findall(r"`([^`]+)`", text_without_fences)
+
+
+# ---------- Validators ----------
+
+
+def validate_headings(orig, comp, result):
+    h1 = extract_headings(orig)
+    h2 = extract_headings(comp)
+
+    if len(h1) != len(h2):
+        result.add_error(f"Heading count mismatch: {len(h1)} vs {len(h2)}")
+
+    if h1 != h2:
+        result.add_warning("Heading text/order changed")
+
+
+def validate_code_blocks(orig, comp, result):
+    c1 = extract_code_blocks(orig)
+    c2 = extract_code_blocks(comp)
+
+    if c1 != c2:
+        result.add_error("Code blocks not preserved exactly")
+
+
+def validate_urls(orig, comp, result):
+    u1 = extract_urls(orig)
+    u2 = extract_urls(comp)
+
+    if u1 != u2:
+        result.add_error(f"URL mismatch: lost={u1 - u2}, added={u2 - u1}")
+
+
+def validate_paths(orig, comp, result):
+    p1 = extract_paths(orig)
+    p2 = extract_paths(comp)
+
+    if p1 != p2:
+        result.add_warning(f"Path mismatch: lost={p1 - p2}, added={p2 - p1}")
+
+
+def validate_bullets(orig, comp, result):
+    b1 = count_bullets(orig)
+    b2 = count_bullets(comp)
+
+    if b1 == 0:
+        return
+
+    diff = abs(b1 - b2) / b1
+
+    if diff > 0.15:
+        result.add_warning(f"Bullet count changed too much: {b1} -> {b2}")
+
+
+def validate_inline_codes(orig, comp, result):
+    c1 = Counter(extract_inline_codes(orig))
+    c2 = Counter(extract_inline_codes(comp))
+
+    if c1 != c2:
+        lost = set(c1.keys()) - set(c2.keys())
+        added = set(c2.keys()) - set(c1.keys())
+        for code, count in c1.items():
+            if code in c2 and c2[code] < count:
+                lost.add(f"{code} (lost {count - c2[code]} of {count} occurrences)")
+        if lost:
+            result.add_error(f"Inline code lost: {lost}")
+        if added:
+            result.add_warning(f"Inline code added: {added}")
+
+
+# ---------- Main ----------
+
+
+def validate(original_path: Path, compressed_path: Path) -> ValidationResult:
+    result = ValidationResult()
+
+    orig = read_file(original_path)
+    comp = read_file(compressed_path)
+
+    validate_headings(orig, comp, result)
+    validate_code_blocks(orig, comp, result)
+    validate_urls(orig, comp, result)
+    validate_paths(orig, comp, result)
+    validate_bullets(orig, comp, result)
+    validate_inline_codes(orig, comp, result)
+
+    return result
+
+
+# ---------- CLI ----------
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) != 3:
+        print("Usage: python validate.py <original> <compressed>")
+        sys.exit(1)
+
+    orig = Path(sys.argv[1]).resolve()
+    comp = Path(sys.argv[2]).resolve()
+
+    res = validate(orig, comp)
+
+    print(f"\nValid: {res.is_valid}")
+
+    if res.errors:
+        print("\nErrors:")
+        for e in res.errors:
+            print(f"  - {e}")
+
+    if res.warnings:
+        print("\nWarnings:")
+        for w in res.warnings:
+            print(f"  - {w}")

package/{.github/agents/implementation-plan.agent.md → .agents/skills/create-implementation-plan/SKILL.md}

@@ -1,49 +1,17 @@
 ---
-description: "Generate an implementation plan for new features or refactoring existing code."
-name: "Implementation Plan Generation Mode"
-tools:
-  [
-    "search/codebase",
-    "search/usages",
-    "vscode/vscodeAPI",
-    "think",
-    "read/problems",
-    "search/changes",
-    "execute/testFailure",
-    "read/terminalSelection",
-    "read/terminalLastCommand",
-    "vscode/openSimpleBrowser",
-    "web/fetch",
-    "findTestFiles",
-    "search/searchResults",
-    "web/githubRepo",
-    "vscode/extensions",
-    "edit/editFiles",
-    "execute/runNotebookCell",
-    "read/getNotebookSummary",
-    "read/readNotebookCellOutput",
-    "search",
-    "vscode/getProjectSetupInfo",
-    "vscode/installExtension",
-    "vscode/newWorkspace",
-    "vscode/runCommand",
-    "execute/getTerminalOutput",
-    "execute/runInTerminal",
-    "execute/createAndRunTask",
-    "execute/getTaskOutput",
-    "execute/runTask",
-  ]
+name: create-implementation-plan
+description: 'Create a new implementation plan file for new features, refactoring existing code or upgrading packages, design, architecture or infrastructure.'
 ---
 
-# Implementation Plan Generation Mode
+# Create Implementation Plan
 
 ## Primary Directive
 
-You are an AI agent operating in planning mode. Generate implementation plans that are fully executable by other AI systems or humans.
+Your goal is to create a new implementation plan file for `${input:PlanPurpose}`. Your output must be machine-readable, deterministic, and structured for autonomous execution by other AI systems or humans.
 
 ## Execution Context
 
-This mode is designed for AI-to-AI communication and automated processing. All plans must be deterministic, structured, and immediately actionable by AI Agents or humans.
+This prompt is designed for AI-to-AI communication and automated processing. All instructions must be interpreted literally and executed systematically without human interpretation or clarification.
 
 ## Core Requirements
 
@@ -51,7 +19,6 @@ This mode is designed for AI-to-AI communication and automated processing. All p
 - Use deterministic language with zero ambiguity
 - Structure all content for automated parsing and execution
 - Ensure complete self-containment with no external dependencies for understanding
-- DO NOT make any code edits - only generate structured plans
 
 ## Plan Structure Requirements
 
@@ -76,8 +43,6 @@ Plans must consist of discrete, atomic phases containing executable tasks. Each
 
 ## Output File Specifications
 
-When creating plan files:
-
 - Save implementation plan files in `/plan/` directory
 - Use naming convention: `[purpose]-[component]-[version].md`
 - Purpose prefixes: `upgrade|refactor|feature|data|infrastructure|process|architecture|design`
@@ -93,7 +58,7 @@ All implementation plans must strictly adhere to the following template. Each se
 - All front matter fields must be present and properly formatted
 - All section headers must match exactly (case-sensitive)
 - All identifier prefixes must follow the specified format
-- Tables must include all required columns with specific task details
+- Tables must include all required columns
 - No placeholder text may remain in the final output
 
 ## Status
@@ -134,21 +99,21 @@ tags: [Optional: List of relevant tags or categories, e.g., `feature`, `upgrade`
 
 - GOAL-001: [Describe the goal of this phase, e.g., "Implement feature X", "Refactor module Y", etc.]
 
-| Task     | Description           | Completed | Date       |
-| -------- | --------------------- | --------- | ---------- |
-| TASK-001 | Description of task 1 | ✅        | 2025-04-25 |
-| TASK-002 | Description of task 2 |           |            |
-| TASK-003 | Description of task 3 |           |            |
+| Task | Description | Completed | Date |
+|------|-------------|-----------|------|
+| TASK-001 | Description of task 1 | ✅ | 2025-04-25 |
+| TASK-002 | Description of task 2 | |  |
+| TASK-003 | Description of task 3 | |  |
 
 ### Implementation Phase 2
 
 - GOAL-002: [Describe the goal of this phase, e.g., "Implement feature X", "Refactor module Y", etc.]
 
-| Task     | Description           | Completed | Date |
-| -------- | --------------------- | --------- | ---- |
-| TASK-004 | Description of task 4 |           |      |
-| TASK-005 | Description of task 5 |           |      |
-| TASK-006 | Description of task 6 |           |      |
+| Task | Description | Completed | Date |
+|------|-------------|-----------|------|
+| TASK-004 | Description of task 4 | |  |
+| TASK-005 | Description of task 5 | |  |
+| TASK-006 | Description of task 6 | |  |
 
 ## 3. Alternatives
 
@@ -189,4 +154,4 @@ tags: [Optional: List of relevant tags or categories, e.g., `feature`, `upgrade`
 
 [Link to related spec 1]
 [Link to relevant external documentation]
-```
+```

package/.agents/skills/create-specification/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: create-specification
+description: 'Create a new specification file for the solution, optimized for Generative AI consumption.'
+---
+
+# Create Specification
+
+Your goal is to create a new specification file for `${input:SpecPurpose}`.
+
+The specification file must define the requirements, constraints, and interfaces for the solution components in a manner that is clear, unambiguous, and structured for effective use by Generative AIs. Follow established documentation standards and ensure the content is machine-readable and self-contained.
+
+## Best Practices for AI-Ready Specifications
+
+- Use precise, explicit, and unambiguous language.
+- Clearly distinguish between requirements, constraints, and recommendations.
+- Use structured formatting (headings, lists, tables) for easy parsing.
+- Avoid idioms, metaphors, or context-dependent references.
+- Define all acronyms and domain-specific terms.
+- Include examples and edge cases where applicable.
+- Ensure the document is self-contained and does not rely on external context.
+
+The specification should be saved in the [/spec/](/spec/) directory and named according to the following convention: `spec-[a-z0-9-]+.md`, where the name should be descriptive of the specification's content and starting with the highlevel purpose, which is one of [schema, tool, data, infrastructure, process, architecture, or design].
+
+The specification file must be formatted in well formed Markdown.
+
+Specification files must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following:
+
+```md
+---
+title: [Concise Title Describing the Specification's Focus]
+version: [Optional: e.g., 1.0, Date]
+date_created: [YYYY-MM-DD]
+last_updated: [Optional: YYYY-MM-DD]
+owner: [Optional: Team/Individual responsible for this spec]
+tags: [Optional: List of relevant tags or categories, e.g., `infrastructure`, `process`, `design`, `app` etc]
+---
+
+# Introduction
+
+[A short concise introduction to the specification and the goal it is intended to achieve.]
+
+## 1. Purpose & Scope
+
+[Provide a clear, concise description of the specification's purpose and the scope of its application. State the intended audience and any assumptions.]
+
+## 2. Definitions
+
+[List and define all acronyms, abbreviations, and domain-specific terms used in this specification.]
+
+## 3. Requirements, Constraints & Guidelines
+
+[Explicitly list all requirements, constraints, rules, and guidelines. Use bullet points or tables for clarity.]
+
+- **REQ-001**: Requirement 1
+- **SEC-001**: Security Requirement 1
+- **[3 LETTERS]-001**: Other Requirement 1
+- **CON-001**: Constraint 1
+- **GUD-001**: Guideline 1
+- **PAT-001**: Pattern to follow 1
+
+## 4. Interfaces & Data Contracts
+
+[Describe the interfaces, APIs, data contracts, or integration points. Use tables or code blocks for schemas and examples.]
+
+## 5. Acceptance Criteria
+
+[Define clear, testable acceptance criteria for each requirement using Given-When-Then format where appropriate.]
+
+- **AC-001**: Given [context], When [action], Then [expected outcome]
+- **AC-002**: The system shall [specific behavior] when [condition]
+- **AC-003**: [Additional acceptance criteria as needed]
+
+## 6. Test Automation Strategy
+
+[Define the testing approach, frameworks, and automation requirements.]
+
+- **Test Levels**: Unit, Integration, End-to-End
+- **Frameworks**: MSTest, FluentAssertions, Moq (for .NET applications)
+- **Test Data Management**: [approach for test data creation and cleanup]
+- **CI/CD Integration**: [automated testing in GitHub Actions pipelines]
+- **Coverage Requirements**: [minimum code coverage thresholds]
+- **Performance Testing**: [approach for load and performance testing]
+
+## 7. Rationale & Context
+
+[Explain the reasoning behind the requirements, constraints, and guidelines. Provide context for design decisions.]
+
+## 8. Dependencies & External Integrations
+
+[Define the external systems, services, and architectural dependencies required for this specification. Focus on **what** is needed rather than **how** it's implemented. Avoid specific package or library versions unless they represent architectural constraints.]
+
+### External Systems
+- **EXT-001**: [External system name] - [Purpose and integration type]
+
+### Third-Party Services
+- **SVC-001**: [Service name] - [Required capabilities and SLA requirements]
+
+### Infrastructure Dependencies
+- **INF-001**: [Infrastructure component] - [Requirements and constraints]
+
+### Data Dependencies
+- **DAT-001**: [External data source] - [Format, frequency, and access requirements]
+
+### Technology Platform Dependencies
+- **PLT-001**: [Platform/runtime requirement] - [Version constraints and rationale]
+
+### Compliance Dependencies
+- **COM-001**: [Regulatory or compliance requirement] - [Impact on implementation]
+
+**Note**: This section should focus on architectural and business dependencies, not specific package implementations. For example, specify "OAuth 2.0 authentication library" rather than "Microsoft.AspNetCore.Authentication.JwtBearer v6.0.1".
+
+## 9. Examples & Edge Cases
+
+    ```code
+    // Code snippet or data example demonstrating the correct application of the guidelines, including edge cases
+    ```
+
+## 10. Validation Criteria
+
+[List the criteria or tests that must be satisfied for compliance with this specification.]
+
+## 11. Related Specifications / Further Reading
+
+[Link to related spec 1]
+[Link to relevant external documentation]
+
+```

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`