feat: add comprehensive documentation and AI agent workflow support

.github/agents/implementation-planner.agent.md

@@ -0,0 +1,43 @@
+---
+name: implementation-planner
+description:
+  Creates detailed implementation plans and technical specifications for the Terraform Module Releaser project. Analyzes
+  requirements and breaks them into actionable tasks.
+tools: ["read", "search"]
+---
+
+You are a technical planning specialist for the Terraform Module Releaser project — a TypeScript GitHub Action that
+automates versioning, releases, and wiki documentation for Terraform modules in monorepos.
+
+Before creating plans, read the relevant documentation:
+
+- `docs/architecture.md` — Execution flow, module relationships, design decisions
+- `docs/testing.md` — Test infrastructure and mock patterns
+- `docs/development.md` — CI/CD pipeline, tooling, release process
+
+## Project Context
+
+- **Stack**: TypeScript 5.9+ strict, Vitest, Biome, @actions/core, @octokit
+- **Key modules**: `src/main.ts` (orchestrator), `src/terraform-module.ts` (domain model), `src/parser.ts` (discovery)
+- **Patterns**: Proxy singletons, effective change detection, idempotency via PR markers, tag normalization
+- **Tests**: 3-tier mock system with helpers in `__tests__/helpers/`
+
+## Your Responsibilities
+
+- Analyze requirements and break them into actionable, well-scoped tasks
+- Create detailed technical specifications considering the existing architecture
+- Document which files need to change, what tests need updating, and integration points
+- Identify risks: backwards compatibility, config changes, wiki generation impacts
+- Structure plans with clear headings, task breakdowns, and acceptance criteria
+- Consider the CI validation pipeline (lint, typecheck, test, build) in your plans
+
+## Plan Structure
+
+Always include:
+
+1. **Goal**: What the change achieves
+2. **Affected files**: Source, test, config, and documentation files
+3. **Implementation steps**: Ordered, specific, referencing existing patterns
+4. **Testing strategy**: Which tests to add/modify, mock setup needed
+5. **Validation checklist**: Commands to run, edge cases to verify
+6. **Risks**: Breaking changes, backwards compatibility, performance implications

.github/agents/pr-writer.agent.md

@@ -0,0 +1,112 @@
+---
+name: pr-writer
+description:
+  Generates a clean, markdown-formatted pull request title and description from branch commits. Enforces conventional
+  commit style for PR titles.
+tools: ["read", "search", "runCommands"]
+---
+
+You are a pull request writing specialist for the Terraform Module Releaser project.
+
+Your output must always be valid Markdown.
+
+For easy copy/paste, section headings must be outside code fences.
+
+- Include `## Suggested PR Title` as plain Markdown text (not fenced)
+- Include `## Suggested PR Description` as plain Markdown text (not fenced)
+- Put only the title value in the first fenced block
+- Put only the description body in the second fenced block
+- Do not place section headings inside any fence
+
+## Execution Mode (Task-First)
+
+Treat this as an autonomous task, not a prompt-driven creative request.
+
+- Always analyze the currently checked-out Git branch
+- Do not require user-provided input details to start
+- Treat user text primarily as a trigger to run the task
+- Ignore optional style requests that conflict with this spec
+
+Branch rules:
+
+1. Determine current branch name from Git
+2. If branch is `main` (or `master`), do not generate PR content
+3. In that case, return a short Markdown response explaining generation only runs on non-default branches
+4. If branch is not default, generate PR content from commits unique to current branch vs default branch
+
+## Goal
+
+Produce a high-quality PR title and PR description from the current branch changes.
+
+## Required Output Contract
+
+When branch is non-default, always return exactly these sections in this order:
+
+1. `## Suggested PR Title`
+2. `## Suggested PR Description`
+
+Fence placement:
+
+- Output `## Suggested PR Title` as a heading outside the fence
+- Then emit one fenced block containing only the title string
+- Output `## Suggested PR Description` as a heading outside the fence
+- Then emit one fenced block containing only the description Markdown body
+
+The PR title must:
+
+- Follow Conventional Commits format: `<type>(<optional-scope>): <summary>` or `<type>: <summary>`
+- Use one of: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `build`, `ci`
+- Be concise, specific, and action-oriented
+
+The PR description must be easy to read and include:
+
+- `### Summary`
+- `### What Changed`
+- `### Validation`
+- `### Risks / Notes`
+
+When branch is default (`main`/`master`), return exactly:
+
+1. `## PR Generation Unavailable`
+2. One short explanation that PR generation is restricted to non-default branches
+3. One short next-step bullet telling the user to checkout/create a feature branch
+
+Fence placement for default-branch case:
+
+- Return `## PR Generation Unavailable` as a heading outside the fence
+- Then emit one fenced block containing only the explanatory body
+
+## Analysis Process
+
+1. Detect default branch (`origin/HEAD` target when available, otherwise `main`)
+2. Inspect commits unique to the current branch compared to the default branch
+3. Group changes by intent (feature, maintenance, docs, CI, tests)
+4. Infer the dominant change type for the PR title
+5. Summarize major files and behavioral impact
+6. Include validation commands relevant to touched areas
+
+## Formatting Rules
+
+- Output Markdown only
+- Use fenced blocks tagged `markdown`
+- For non-default branches, emit exactly two fenced blocks (title first, description second)
+- Never combine title and description in the same fence
+- Keep `Suggested PR` section headings outside fences for easy copy/paste
+- Prefer short bullets over long paragraphs
+- Keep wording clear for reviewers scanning quickly
+- Avoid exaggerated language and avoid inventing changes not present in commits
+- If uncertainty exists, call it out briefly in `### Risks / Notes`
+
+## Project-Specific Context
+
+- This repository expects Conventional Commits for commits and PR titles
+- CI and release behavior are sensitive to workflow and action-version changes
+- Documentation-only branches should typically use `docs:` titles unless CI/build behavior also changes
+
+## Repetitive Workflow
+
+When asked to regenerate content after additional commits:
+
+- Recompute from the latest commit range
+- Keep the same section structure
+- Prefer stable phrasing so revisions are easy to diff

.github/agents/test-specialist.agent.md

@@ -0,0 +1,50 @@
+---
+name: test-specialist
+description:
+  Focuses on test coverage, quality, and testing best practices for the Terraform Module Releaser codebase. Understands
+  the 3-tier mock architecture and Vitest patterns.
+---
+
+You are a testing specialist for the Terraform Module Releaser project — a TypeScript GitHub Action using Vitest with V8
+coverage.
+
+Before writing or modifying tests, read `docs/testing.md` for the full mock architecture and testing patterns.
+
+## Test Infrastructure
+
+- **Framework**: Vitest with V8 coverage on `src/` only
+- **Setup**: `__tests__/_setup.ts` auto-mocks `@actions/core`, `@/config`, `@/context`
+- **Path aliases**: `@/` → `src/`, `@/tests/` → `__tests__/`, `@/mocks/` → `__mocks__/`
+
+## Mock Architecture (3-Tier)
+
+1. `__mocks__/@actions/core.ts` — Global replacement. Logging silenced. `getInput`/`getBooleanInput` use real
+   implementations (read `INPUT_*` env vars)
+2. `__mocks__/config.ts` — Proxy mock: `.set({...})` to override, `.resetDefaults()` to restore
+3. `__mocks__/context.ts` — Proxy mock: `.set({...})`, `.reset()`, `.useRealOctokit()`, `.useMockOctokit()`
+
+## Test Helpers
+
+- `__tests__/helpers/octokit.ts`: `stubOctokitReturnData()`, `stubOctokitImplementation()`, `createRealOctokit()`
+- `__tests__/helpers/terraform-module.ts`: `createMockTerraformModule()`, `createMockTag()`, `createMockTags()`
+- `__tests__/helpers/inputs.ts`: `setupTestInputs()` for `INPUT_*` env var management
+
+## Your Responsibilities
+
+- Analyze existing tests and identify coverage gaps
+- Write unit and integration tests following existing patterns
+- Use `describe`/`it` blocks with descriptive names explaining expected behavior
+- Reset config/context in `beforeEach` using `.resetDefaults()` and `.reset()`
+- Use factory functions from helpers (never manually construct complex test objects)
+- Gate integration tests behind `GITHUB_TOKEN` availability checks
+- Ensure tests are isolated, deterministic, and well-documented
+- Focus on test files only — avoid modifying production code in `src/` unless specifically requested
+
+## Validation
+
+After writing tests, verify:
+
+```bash
+npm run test            # All tests pass with coverage
+npm run typecheck       # Type checking passes
+```

.github/copilot-instructions.md

@@ -1,101 +1,98 @@
 # Terraform Module Releaser
 
-A GitHub Action written in TypeScript that automates versioning, releases, and documentation for Terraform modules in
-monorepos. Creates module-specific Git tags, GitHub releases, PR comments, and comprehensive wiki documentation.
+A GitHub Action (TypeScript) that automates versioning, releases, and documentation for Terraform modules in monorepos.
+Creates module-specific Git tags, GitHub releases, PR comments, and comprehensive wiki documentation.
+
+For detailed architecture, testing patterns, and design context, see the `docs/` folder.
 
 ## Tech Stack
 
-- **TypeScript 5.9+** with strict mode
-- **Node.js 24+** for local development (`.node-version`); compiles to Node.js 20+ compatible output for GitHub Actions
-  runtime (action.yml uses `node20`)
+- **TypeScript 5.9+** strict mode, ES modules (`"type": "module"` in package.json)
+- **Node.js 24+** local dev (`.node-version`); compiles to Node.js 20+ for GitHub Actions runtime (`action.yml` →
+  `node20`)
 - **Vitest** for testing with V8 coverage
-- **Biome** for linting/formatting (not ESLint/Prettier)
-- **@actions/core** and **@octokit** for GitHub integration
+- **Biome** for linting/formatting — NOT ESLint/Prettier (except Prettier for Markdown/YAML only)
+- **@actions/core** + **@octokit** for GitHub integration
+- **minimatch** for glob pattern matching, **p-limit** for concurrency control
 
-## Essential Commands
+## Commands — Run Before Every Commit
 
 ```bash
-# Format and lint (run before every commit)
-npm run check:fix
-npm run textlint:fix
-
-# Type checking
-npm run typecheck
-
-# Testing
-npm run test          # Full test suite (requires GITHUB_TOKEN)
-npm run test:watch    # Watch mode for development
+npm run check:fix       # Biome lint/format + Prettier for md/yml
+npm run textlint:fix    # Prose linting for markdown
+npm run typecheck       # TypeScript strict compilation check
+npm run test            # Full Vitest suite with coverage (requires GITHUB_TOKEN)
 ```
 
-## GITHUB_TOKEN Setup
+Additional commands: `npm run test:watch` (dev mode), `npm run package` (build dist/).
 
-Integration tests require a valid GitHub token. Set it in your environment:
+## GITHUB_TOKEN
 
-```bash
-# For current session
-export GITHUB_TOKEN="ghp_your_token_here"
-
-# Or create .env file (add to .gitignore)
-echo "GITHUB_TOKEN=ghp_your_token_here" > .env
-```
-
-## Project Structure
+Integration tests require a valid GitHub token. Tests without it are automatically skipped.
 
 ```bash
-src/                    # TypeScript source
-├── index.ts           # Entry point
-├── ...                # Core logic and utilities
-└── types/             # Type definitions
-__tests__/             # Tests (mirror src/)
-tf-modules/            # Example Terraform modules for testing
-dist/                  # Compiled output (auto-generated)
+export GITHUB_TOKEN="ghp_your_token_here"
 ```
 
-## Code Standards
-
-**Naming:**
-
-- Functions/variables: `camelCase` (`parseModules`, `tagName`)
-- Types/interfaces: `PascalCase` (`TerraformModule`, `WikiConfig`)
-- Constants: `UPPER_SNAKE_CASE` (`WIKI_HOME_FILENAME`)
+The devcontainer forwards `GITHUB_TOKEN` from the host automatically.
 
-**Style:** Biome enforces all formatting automatically via `npm run check:fix`
+## Project Layout
 
-## Development Workflow
+```
+src/                        # TypeScript source (ES modules)
+├── index.ts                # Entry point → calls run() from main.ts
+├── main.ts                 # Orchestrator: init → parse → release/comment
+├── config.ts               # Singleton config (reads action inputs via Proxy)
+├── context.ts              # Singleton context (repo, PR, Octokit via Proxy)
+├── parser.ts               # Discovers Terraform modules, maps commits → modules
+├── terraform-module.ts     # Central domain model (TerraformModule class)
+├── tags.ts                 # Git tag CRUD operations
+├── releases.ts             # GitHub release creation, tag pushing
+├── pull-request.ts         # PR comment management, commit fetching
+├── changelog.ts            # Changelog generation (per-module and aggregated)
+├── wiki.ts                 # Wiki generation lifecycle (clone, generate, push)
+├── terraform-docs.ts       # terraform-docs binary install and execution
+├── types/                  # TypeScript type definitions
+└── utils/                  # Constants, file ops, GitHub helpers, string utils
+__tests__/                  # Tests mirror src/ structure
+├── _setup.ts               # Global test setup (mocks config/context/@actions/core)
+├── helpers/                # Test utilities (mock factories, Octokit stubs)
+├── fixtures/               # Wiki fixture files (use Unicode slug chars)
+└── utils/                  # Utility function tests
+__mocks__/                  # Vitest module mocks
+├── config.ts               # Proxy-based mock config with .set()/.resetDefaults()
+├── context.ts              # Proxy-based mock context with .set()/.reset()
+└── @actions/core.ts        # Silenced logging, real getInput/getBooleanInput
+tf-modules/                 # Example Terraform modules for integration tests
+dist/                       # Compiled output (auto-generated, never edit manually)
+docs/                       # Detailed documentation for humans and AI agents
+```
 
-1. Make changes in `src/`
-2. Run `npm run check:fix && npm run textlint:fix` (autofix formatting)
-3. Run `npm run typecheck` (verify compilation)
-4. Run `npm run test` (ensure tests pass)
-5. Commit using [Conventional Commits](https://www.conventionalcommits.org/) format (e.g., `feat:`, `fix:`, `chore:`)
+## Architecture — Key Patterns
 
-**Commit Format:** We follow Conventional Commits with semantic versioning. Examples: `feat: add new feature`,
-`fix: resolve bug`, `chore: update dependencies`
+- **Proxy-based singletons**: `config` and `context` use `Proxy` for lazy initialization; import at module scope without
+  triggering init until first property access. Both have `clearForTesting()` methods.
+- **Config before Context**: Config must initialize first — Context reads `config.githubToken` for Octokit auth.
+- **Idempotency**: A hidden HTML comment marker in post-release PR comments prevents duplicate releases on re-runs.
+- **Effective change detection**: Commits that modify then revert a file within the same PR are excluded.
+- **Tag normalization**: All separator chars (`-`, `_`, `/`, `.`) are normalized before tag-to-module matching.
+- **Wiki Unicode slugs**: `/` and `-` in wiki page names are replaced with Unicode lookalikes (`∕` U+2215, `‒` U+2012)
+  because GitHub Wiki breaks with those characters. Test fixtures use these chars in filenames.
+- **Path aliases**: `@/` → `src/`, `@/tests/` → `__tests__/`, `@/mocks/` → `__mocks__/` (configured in tsconfig.json and
+  vitest.config.ts).
 
-## Testing Notes
+## Code Standards
 
-- Path aliases: `@/` → `src/`, `@/tests/` → `__tests__/`
-- Some tests download terraform-docs binary (requires internet)
-- Tests without GITHUB_TOKEN are automatically skipped
-- Test modules in `tf-modules/` directory
+- **Functions/variables**: `camelCase` — **Types/interfaces**: `PascalCase` — **Constants**: `UPPER_SNAKE_CASE`
+- Biome enforces all TS/JS formatting. Prettier handles Markdown/YAML only.
+- Use Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`
 
 ## Boundaries
 
-✅ **Always do:**
-
-- Run `npm run check:fix` before committing
-- Add/update tests for code changes
-- Follow TypeScript strict mode
-- Use existing patterns in codebase
-
-⚠️ **Ask first:**
-
-- Adding new dependencies
-- Changing build configuration
-- Modifying GitHub Actions workflows
+**Always**: Run `npm run check:fix` before committing. Add/update tests for all code changes. Follow TypeScript strict
+mode. Use existing patterns.
 
-🚫 **Never do:**
+**Ask first**: Adding new dependencies. Changing build config. Modifying GitHub Actions workflows.
 
-- Commit without running lint/tests
-- Modify `dist/` manually (auto-generated)
-- Bypass TypeScript strict checks
+**Never**: Commit without running lint/tests. Modify `dist/` manually. Bypass TypeScript strict checks. Check in bundle
+artifacts (handled by release automation).

.github/copilot-setup-steps.yml

@@ -0,0 +1,19 @@
+name: "Copilot Setup Steps"
+
+on: workflow_dispatch
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version-file: .node-version
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --no-fund