@abarcenas/ai-workflow-template 1.46.0 → 1.48.0

package/.opencode/agents/orchestrator/{tdd-orchestrator.agent.md → tdd-orchestrator.md}

@@ -1,13 +1,10 @@
 ---
 description: "Test-Driven Development orchestrator that enforces a RED-GREEN-REFACTOR pipeline. Writes tests first via unit-tester, then implements code via coder, verifies coverage ≥90%, and returns to test-writing if thresholds are not met. Tracks all test suites in memory-bank."
-name: "TDD Orchestrator - Test-Driven Development"
-permission:
-  search: allow
-  read: allow
-  agent: allow
-  todo: allow
-  "memory-bank/*": allow
-  "knowledgebase/*": allow
+mode: primary
+permissions:
+  - { action: edit,  resource: "*",    effect: deny }
+  - { action: edit,  resource: "*.md", effect: allow }
+  - { action: shell, resource: "*",    effect: allow }
 ---
 
 # TDD Orchestrator - Test-Driven Development
@@ -28,11 +25,11 @@ You are a Test-Driven Development orchestration agent that enforces a strict RED
 
 | Role | Agent File | subagent_type | Typical Tools | When to Deploy |
 |---|---|---|---|---|---|
-| implementer | `implementer.agent.md` | `implementer` | read, search, edit, execute | Translating requirements into implementation plans with test/code batch tables |
-| unit-tester | `unit-tester.agent.md` | `unit-tester` | read, search, edit (test files only), execute | RED phase: write failing tests. VERIFY phase: run tests + check coverage |
-| coder | `coder.agent.md` | `coder` | read, search, edit, execute | GREEN phase: write minimal production code to pass tests |
-| reviewer | `reviewer.agent.md` | `reviewer` | read, search, github/* | Code review, security audit, quality gates on both tests and implementation |
-| tracker | `tracker.agent.md` | `tracker` | read, search | Doc recording — runs after pipeline to log finished work |
+| implementer | `implementer.md` | `implementer` | read, search, edit, execute | Translating requirements into implementation plans with test/code batch tables |
+| unit-tester | `unit-tester.md` | `unit-tester` | read, search, edit (test files only), execute | RED phase: write failing tests. VERIFY phase: run tests + check coverage |
+| coder | `coder.md` | `coder` | read, search, edit, execute | GREEN phase: write minimal production code to pass tests |
+| reviewer | `reviewer.md` | `reviewer` | read, search, github/* | Code review, security audit, quality gates on both tests and implementation |
+| tracker | `tracker.md` | `tracker` | read, search | Doc recording — runs after pipeline to log finished work |
 
 ## TDD Pipeline Overview
 
@@ -63,12 +60,12 @@ Delegate bootstrap checks to a sub-agent. Do NOT read or check any files yoursel
 Invoke a sub-agent (use `subagent_type "implementer"`) to check and bootstrap the project:
 
 ```
-This phase must be performed as the agent "Implementer - Implementation Planning" defined in ".opencode/agents/implementer.agent.md".
+This phase must be performed as the agent "Implementer - Implementation Planning" defined in ".opencode/agents/implementer.md".
 
 BOOTSTRAP CONTEXT - Check and initialize project scaffolding:
 
 IMPORTANT:
-- Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+- Read and apply the entire agent spec file (tools, constraints, quality standards).
 - Base path: "{basePath}".
 - Check if `docs/.architecture-context.md` exists with real content.
 - If missing or template-only, run the architecture-blueprint-generator skill by reading ".agents/skills/architecture-blueprint-generator/SKILL.md" and following its instructions to analyze the codebase and generate architecture context.
@@ -120,10 +117,10 @@ The implementer creates the plan document with **two separate batch tables** for
 3. Invoke the sub-agent using the Task tool with `subagent_type "implementer"`:
 
 ```
-This phase must be performed as the agent "Implementation Plan Generation" defined in ".opencode/agents/implementer.agent.md".
+This phase must be performed as the agent "Implementation Plan Generation" defined in ".opencode/agents/implementer.md".
 
 IMPORTANT:
-- Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+- Read and apply the entire agent spec file (tools, constraints, quality standards).
 - Work on "{work_unit}" with base path: "{basePath}".
 - Produce a plan file in /plan/ with TWO separate batch execution tables:
   1. **Test Batch Summary** — tasks for writing tests (unit-tester work). Each test task must specify: the test file to create, the component/function under test, expected behaviors to cover, and dependencies on other test tasks.
@@ -153,10 +150,10 @@ IMPORTANT:
    b. Log: `"Test Batch {letter}: launching {N} parallel unit-tester tasks — {task_ids}"`
    c. Launch **one Task tool invocation per test task**, all concurrently, using `subagent_type "unit-tester"`:
    ```
-   This phase must be performed as the agent "Unit Tester - Test Coverage" defined in ".opencode/agents/unit-tester.agent.md".
+   This phase must be performed as the agent "Unit Tester - Test Coverage" defined in ".opencode/agents/unit-tester.md".
 
    IMPORTANT:
-   - Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+   - Read and apply the entire agent spec file (tools, constraints, quality standards).
    - TDD CONTEXT: This is the RED phase. You are writing tests that define expected behavior BEFORE any implementation code exists. These tests SHOULD fail when run — that is correct and expected in TDD.
    - Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
    - Work on "Write tests for task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
@@ -197,10 +194,10 @@ IMPORTANT:
    b. Log: `"Impl Batch {letter}: launching {N} parallel coder tasks — {task_ids}"`
    c. Launch **one Task tool invocation per implementation task**, all concurrently, using `subagent_type "coder"`:
    ```
-   This phase must be performed as the agent "Coder - Implementation" defined in ".opencode/agents/coder.agent.md".
+   This phase must be performed as the agent "Coder - Implementation" defined in ".opencode/agents/coder.md".
 
    IMPORTANT:
-   - Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+   - Read and apply the entire agent spec file (tools, constraints, quality standards).
    - TDD CONTEXT: This is the GREEN phase. Write the MINIMAL production code necessary to pass all existing tests. Do NOT add features beyond what the tests specify. The tests were written first and define the contract you must fulfill.
    - Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
    - Work on "Implement task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
@@ -236,10 +233,10 @@ IMPORTANT:
 3. Invoke the sub-agent using the Task tool with `subagent_type "unit-tester"`:
 
 ```
-This phase must be performed as the agent "Unit Tester - Test Coverage" defined in ".opencode/agents/unit-tester.agent.md".
+This phase must be performed as the agent "Unit Tester - Test Coverage" defined in ".opencode/agents/unit-tester.md".
 
 IMPORTANT:
-- Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+- Read and apply the entire agent spec file (tools, constraints, quality standards).
 - TDD CONTEXT: This is the VERIFY phase. Run ALL test files in the project. Report:
   - Total tests: {count}
   - Passed: {count}
@@ -276,10 +273,10 @@ Review both test code and implementation code for quality, correctness, and adhe
 3. Invoke the sub-agent using the Task tool with `subagent_type "reviewer"`:
 
 ```
-This phase must be performed as the agent "Reviewer - Code Quality" defined in ".opencode/agents/reviewer.agent.md".
+This phase must be performed as the agent "Reviewer - Code Quality" defined in ".opencode/agents/reviewer.md".
 
 IMPORTANT:
-- Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+- Read and apply the entire agent spec file (tools, constraints, quality standards).
 - TDD CONTEXT: Review BOTH the test files and the implementation files. Verify that:
   - Tests are comprehensive and meaningful (not just mocks returning canned values).
   - Implementation is minimal and does not contain untested code paths.
@@ -304,10 +301,10 @@ After the pipeline finishes executing, delegate to the tracker agent to document
 1. Invoke the tracker using the Task tool with subagent_type "tracker":
 
 ```
-This phase must be performed as the agent "Tracker - Documentation Recorder" defined in ".opencode/agents/tracker.agent.md".
+This phase must be performed as the agent "Tracker - Documentation Recorder" defined in ".opencode/agents/tracker.md".
 
 IMPORTANT:
-- Read and apply the entire .agent.md spec (tools, constraints, quality standards).
+- Read and apply the entire agent spec file (tools, constraints, quality standards).
 - Base path: "{basePath}".
 - Read the orchestrator log at "docs/.orchestrator-log.md" for the full pipeline record.
 - Read any artifact files referenced in the log.
@@ -338,12 +335,12 @@ After every pipeline (or at the user's request), delegate to a sub-agent to pers
 Invoke the tracker (use `subagent_type "tracker"`) with the pipeline context:
 
 ```
-This phase must be performed as the agent "Tracker - Documentation Recorder" defined in ".opencode/agents/tracker.agent.md".
+This phase must be performed as the agent "Tracker - Documentation Recorder" defined in ".opencode/agents/tracker.md".
 
 PERSIST LESSONS - Record pipeline knowledge:
 
 IMPORTANT:
-- Read and apply the entire .agent.md spec.
+- Read and apply the entire agent spec file.
 - Base path: "{basePath}".
 - Read the orchestrator log at "docs/.orchestrator-log.md" for the full pipeline record.
 - Append a new "Session" entry to ".agents/instructions/learned-knowledge.instructions.md" with:

package/.opencode/agents/{plan.agent.md → planner.md}

@@ -1,14 +1,9 @@
 ---
 description: "Strategic planning and architecture assistant focused on thoughtful analysis before implementation. Helps developers understand codebases, clarify requirements, and develop comprehensive implementation strategies."
-name: "Plan Mode - Strategic Planning & Architecture"
-permission:
-  read: allow
-  search: allow
-  edit: allow
-  skill: allow
-  question: allow
-  webfetch: allow
-  websearch: allow
+mode: primary
+permissions:
+  - { action: edit,  resource: "*",    effect: allow }
+  - { action: shell, resource: "*",    effect: allow }
 ---
 
 # Plan Mode - Strategic Planning & Architecture Assistant

package/.opencode/agents/{researcher.agent.md → researcher.md}

@@ -1,14 +1,10 @@
 ---
 description: "Deep-dive research and investigation specialist. Handles technical unknowns, library evaluation, spike validation, and information gathering from documentation, codebases, and web sources."
-name: "Researcher - Technical Investigation"
-permission:
-  read: allow
-  search: allow
-  web: allow
-  "ddg-search/*": allow
-  "context7/*": allow
-  "memory-bank/*": allow
-  "knowledgebase/*": allow
+mode: all
+permissions:
+  - { action: edit,  resource: "*",    effect: deny }
+  - { action: edit,  resource: "*.md", effect: allow }
+  - { action: shell, resource: "*",    effect: deny }
 ---
 
 # Technical spike research mode

package/.opencode/agents/{reviewer.agent.md → reviewer.md}

@@ -1,13 +1,10 @@
 ---
 description: "Code review and quality assurance specialist. Reviews code for correctness, security vulnerabilities, performance issues, maintainability, and adherence to project standards."
-name: "Reviewer - Code Quality"
-permission:
-  read: allow
-  search: allow
-  edit: allow
-  "github/*": allow
-  "memory-bank/*": allow
-  "knowledgebase/*": allow
+mode: all
+permissions:
+  - { action: edit,  resource: "*",    effect: deny }
+  - { action: edit,  resource: "*.md", effect: allow }
+  - { action: shell, resource: "*",    effect: deny }
 ---
 
 # Reviewer - Code Quality

package/.opencode/agents/{scope.agent.md → scope.md}

@@ -1,14 +1,10 @@
 ---
 description: "Feature scoping specialist. Narrows underspecified feature requests through rounds of numbered questions with recommended answers, then writes a spike document that researcher and implementer can consume."
-name: "Scope - Feature Scoping"
-permission:
-  read: allow
-  search: allow
-  edit: allow
-  skill: allow
-  question: allow
-  "memory-bank/*": allow
-  "knowledgebase/*": allow
+mode: all
+permissions:
+  - { action: edit,  resource: "*",    effect: deny }
+  - { action: edit,  resource: "*.md", effect: allow }
+  - { action: shell, resource: "*",    effect: deny }
 ---
 
 # Scope - Feature Scoping

package/.opencode/agents/{tracker.agent.md → tracker.md}

@@ -1,14 +1,10 @@
 ---
 description: "Documentation recorder that reads completed agent outputs and appends structured documentation to docs/<feature>/<agent>.md. Runs once after a pipeline finishes to produce a human-readable record of what was accomplished."
-name: "Tracker - Documentation Recorder"
-permission:
-  read: allow
-  search: allow
-  glob: allow
-  edit: allow
-  write: allow
-  "memory-bank/*": allow
-  "knowledgebase/*": allow
+mode: all
+permissions:
+  - { action: edit,  resource: "*",    effect: deny }
+  - { action: edit,  resource: "*.md", effect: allow }
+  - { action: shell, resource: "*",    effect: deny }
 ---
 
 # Tracker - Documentation Recorder

package/.opencode/agents/{unit-tester.agent.md → unit-tester.md}

@@ -1,13 +1,9 @@
 ---
 description: "Unit and integration testing specialist. Writes comprehensive tests, improves coverage, validates edge cases, and ensures code quality through automated testing."
-name: "Unit Tester - Test Coverage"
-permission:
-  read: allow
-  search: allow
-  edit: allow
-  execute: allow
-  "memory-bank/*": allow
-  "knowledgebase/*": allow
+mode: all
+permissions:
+  - { action: edit,  resource: "*",    effect: allow }
+  - { action: shell, resource: "*",    effect: allow }
 ---
 
 # Unit Tester - Test Coverage

package/.prettierignore

@@ -0,0 +1,26 @@
+# Project-owned. Sync never overwrites this file.
+# Keep formatters away from files managed by @abarcenas/ai-workflow-template:
+# a formatting pass over managed files makes every future sync skip them.
+
+# Managed agent configuration
+.agents/
+.opencode/agents/
+.opencode/commands/
+
+# Managed root files
+AGENTS.md
+AGENTS.project.md
+skills-lock.json
+
+# Managed scripts (scripts/sync.js scriptsToSync)
+scripts/memory-cli.js
+scripts/memory-index.js
+scripts/bump-version.js
+scripts/validate-memory-schema.js
+scripts/vocab-sync.js
+scripts/mcp-memory-server.js
+scripts/mcp/playwright-mcp-launcher.js
+scripts/knowledgebase-cli.js
+scripts/knowledgebase-index.js
+scripts/mcp-knowledgebase-server.js
+scripts/knowledgebase-init.sql

package/AGENTS.md

@@ -9,10 +9,14 @@ This project includes AI-assisted development configuration distributed through
 - `.opencode/agents/` — Specialized agent definitions for planning, research, and implementation
 - `.agents/prompts/` — Reusable prompt templates
 
+## Project-Specific Rules
+
+Put project-specific agent rules in `AGENTS.project.md` at the repository root. That file is project-owned: sync never overwrites or prunes it, and `--force` cannot replace it. New projects load it automatically through the `instructions` entry in `opencode.json`.
+
 ## Core Workflow
 
 1. **Understand before acting** — Read relevant instructions from `.agents/instructions/` before working with specific technologies
-2. **Plan before implementing** — Narrow underspecified work with the `scope` agent first, then use the `.opencode/agents/plan.agent.md` (optional deep planning) or `.opencode/agents/implementer.agent.md` patterns for structured work
+2. **Plan before implementing** — Narrow underspecified work with the `scope` agent first, then use the `.opencode/agents/planner.md` (optional deep planning) or `.opencode/agents/implementer.md` patterns for structured work
 3. **Track progress** — Update `memory-bank/activeContext.md` and `memory-bank/progress.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`)
 
@@ -105,9 +109,9 @@ Five skills installed from `mattpocock/skills` (pinned at `v1.3.1`) drive scopin
 
 ### Scope agent
 
-`.opencode/agents/scope.agent.md` is the front door for underspecified work. It runs `grilling` in rounds against a single draft file, emits each round's frontier as numbered questions with a recommended answer per question, and stops when the frontier is empty or the remaining unknowns are explicitly deferred.
+`.opencode/agents/scope.md` is the front door for underspecified work. It runs `grilling` in rounds against a single draft file, emits each round's frontier as numbered questions with a recommended answer per question, and stops when the frontier is empty or the remaining unknowns are explicitly deferred.
 
-It terminates by writing `docs/spike-<feature>.md` — the spike document `.opencode/agents/researcher.agent.md` already expects as its input. From there the work continues to `researcher` (open questions need evidence), `implementer` (scope settled, planning remains), or `architect` (the shape of the system is the open problem).
+It terminates by writing `docs/spike-<feature>.md` — the spike document `.opencode/agents/researcher.md` already expects as its input. From there the work continues to `researcher` (open questions need evidence), `implementer` (scope settled, planning remains), or `architect` (the shape of the system is the open problem).
 
 The agent has no command-execution permission: it never builds, runs, or tests code. When a question can only be settled empirically it emits `prototype needed: <question>` with a branch, and that work is handed off to `coder` (logic) or `designer` (UI).
 
@@ -124,7 +128,7 @@ These agent workflows (from `.opencode/agents/`) define specialized modes of ope
 
 Underspecified work does not start here. The default front door is the **`scope` agent** (see [`## Agent skills`](#agent-skills)): it narrows the request through grilling rounds and writes `docs/spike-<feature>.md`, which is handed to `researcher` when open questions need evidence, or to `implementer` when only planning remains.
 
-`.opencode/agents/plan.agent.md` remains available as an **optional deep-planning mode** for work that is already scoped but needs a step-by-step plan. It is not deleted and not deprecated — it is demoted in the default flow only. When you use it, follow this sequence:
+`.opencode/agents/planner.md` remains available as an **optional deep-planning mode** for work that is already scoped but needs a step-by-step plan. It is not deleted and not deprecated — it is demoted in the default flow only. When you use it, 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
@@ -176,7 +180,7 @@ Always ask user permission before: creating files, running commands, modifying t
 
 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`.
+The agent file is at `.opencode/agents/orchestrator/feature-pipeline.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.
 
@@ -197,7 +201,7 @@ implementer (PLAN) → unit-tester∥ (RED) → coder∥ (GREEN) → unit-tester
 | 5 | REVIEW | reviewer | Audits tests + code for quality, security, patterns |
 | 6 | DOCUMENT | tracker | Records results to `docs/tracker-log.md` |
 
-The agent file is at `.opencode/agents/orchestrator/tdd-orchestrator.agent.md`.
+The agent file is at `.opencode/agents/orchestrator/tdd-orchestrator.md`.
 
 **When to use:** Any feature, bug fix, or refactor where tests should be written first. The orchestrator automatically selects this pipeline when testable code changes are requested.
 

package/README.md

@@ -75,8 +75,29 @@ npm run sync                # Normal sync
 - New files are copied automatically
 - Unmodified files are refreshed from the package
 - Locally edited files are preserved (skipped by default)
+- Project-owned files are never overwritten or pruned after creation, and `--force` cannot replace them
 - GitHub Actions workflows are excluded from consumer sync (`.github/workflows/`)
 
+> `--dry-run` previews copies and prunes, but missing scaffold files (memory-bank stubs, `opencode.json`, `AGENTS.project.md`, `.prettierignore`) are still created. This matches the pre-existing scaffold behaviour.
+
+### Project-owned files
+
+`AGENTS.project.md` is the supported home for project-specific agent rules. It is created if absent, then treated as project-owned: sync never overwrites or prunes it, `--force` cannot replace it, and deleting it recreates it on the next sync. New projects load it through `"instructions": ["AGENTS.project.md"]` in `opencode.json`; a project created before that entry existed must add it once, because sync never rewrites an existing `opencode.json`.
+
+The same ownership rule protects `opencode.json`, `.prettierignore`, and `.agents/instructions/learned-knowledge.instructions.md`. `.agents-sync-ignore` is also protected from overwrite and deletion, but sync does **not** read or honour its contents yet — do not rely on it.
+
+`__project__/<file>` entries in `.agents-sync-manifest.json` are reporting metadata written only when sync creates the file. Files that already existed before the upgrade are intentionally absent, because sync has no managed baseline for them.
+
+The package ships a `.prettierignore` and scaffolds it when absent. New projects get coverage automatically for `.agents/`, `.opencode/agents/`, `.opencode/commands/`, `AGENTS.md`, `skills-lock.json`, and every synced script; the shipped file also ignores `AGENTS.project.md`, though that file is not hash-managed. Existing projects keep their own `.prettierignore` untouched (it is project-owned), so if it does not cover every managed path sync prints one warning:
+
+```text
+[ai-workflow-template] Existing .prettierignore does not protect managed files; merge the patterns from node_modules/@abarcenas/ai-workflow-template/.prettierignore
+```
+
+Merge those patterns manually — sync never edits the file. Template-side additions to `rootFiles` or `scriptsToSync` also require a matching manual line in an existing project; the shipped file only updates the defaults for new projects. A formatter run over managed files rewrites their hashes, so every later sync skips them and the consumer stops receiving template updates.
+
+If sync warns `Skipped locally modified root file: AGENTS.md`, move those local rules into `AGENTS.project.md`, restore the managed file from `node_modules/@abarcenas/ai-workflow-template/AGENTS.md`, then re-run sync.
+
 ## Core Structure
 
 Post-install, your project receives this structure:
@@ -90,6 +111,7 @@ Post-install, your project receives this structure:
 .github/workflows/  # CI/CD automation (excluded from sync)
 docs/               # Guides (e.g. playwright-mcp-configuration.md)
 AGENTS.md           # Master instruction file with agent guidance
+AGENTS.project.md   # Project-owned rules (recreated if deleted, never overwritten)
 ```
 
 ## Multi-Agent Orchestrator
@@ -98,18 +120,18 @@ AGENTS.md           # Master instruction file with agent guidance
 
 | Agent | File | Role |
 | --- | --- | --- |
-| Orchestrator | `.opencode/agents/orchestrator/orchestrator.agent.md` | Master — analyzes requests, builds pipelines, delegates |
-| Scope | `.opencode/agents/scope.agent.md` | Conditional front door for underspecified requests — grilling rounds, then a spike doc |
-| 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 |
+| Orchestrator | `.opencode/agents/orchestrator/orchestrator.md` | Master — analyzes requests, builds pipelines, delegates |
+| Scope | `.opencode/agents/scope.md` | Conditional front door for underspecified requests — grilling rounds, then a spike doc |
+| Researcher | `.opencode/agents/researcher.md` | Technical investigation, library evaluation |
+| Architect | `.opencode/agents/architect.md` | System design, component architecture |
+| Implementer | `.opencode/agents/implementer.md` | Translates designs into implementation plans |
+| Designer | `.opencode/agents/designer.md` | UI/UX, styling, responsive design |
+| Coder | `.opencode/agents/coder.md` | Production code implementation |
+| Unit Tester | `.opencode/agents/unit-tester.md` | Unit and integration tests |
+| E2E Tester | `.opencode/agents/e2e-tester.md` | Playwright browser tests |
+| Reviewer | `.opencode/agents/reviewer.md` | Code review, security audit |
+| Deployer | `.opencode/agents/deployer.md` | CI/CD, deployment scripts |
+| Tracker | `.opencode/agents/tracker.md` | Documentation recorder |
 
 ### How to Use
 
@@ -286,6 +308,8 @@ npm run memory:normalize   # Normalize frontmatter (runs automatically on instal
 
 - Uses `INIT_CWD` to install against the consuming project (not the package dir)
 - Local changes are always preserved unless `--force` is used
+- Project-owned files (`AGENTS.project.md`, `opencode.json`, `.prettierignore`, learned knowledge) are created if absent and never overwritten or pruned after that, even with `--force`
+- Do not add `AGENTS.project.md` or `opencode.json` to `package.json` `files`: both are scaffolded create-if-absent and must never ship from the package
 - `AGENTS.md` is the main instruction file agents should read
 - Package assumes the public npm registry
 - Playwright MCP integration is documented in `docs/`

package/opencode.mcp.example.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://opencode.ai/config.json",
+  "instructions": ["AGENTS.project.md"],
   "mcp": {
     "chrome-devtools": {
       "type": "local",
@@ -18,10 +19,9 @@
      },
     "github": {
       "type": "local",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN"
+      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
+      "environment": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}"
       },
       "enabled": true
     },
@@ -29,19 +29,19 @@
       "type": "remote",
       "url": "https://mcp.context7.com/mcp",
       "headers": {
-        "CONTEXT7_API_KEY": "YOUR_API_KEY"
+        "CONTEXT7_API_KEY": "{env:CONTEXT7_TOKEN}"
       },
       "enabled": true
     },
     "playwright": {
       "type": "local",
-      "command": "node",
-      "args": ["scripts/mcp/playwright-mcp-launcher.js"],
-      "env": {
-        "HEADLESS": "$HEADLESS",
-        "SLOW_MO": "$SLOW_MO",
-        "VIEWPORT": "$VIEWPORT"
+      "command": ["node", "scripts/mcp/playwright-mcp-launcher.js"],
+      "environment": {
+        "HEADLESS": "{env:HEADLESS}",
+        "SLOW_MO": "{env:SLOW_MO}",
+        "VIEWPORT": "{env:VIEWPORT}"
       },
+      "timeout": 120000,
       "enabled": true
     },
     "example-server": {
@@ -66,6 +66,7 @@
     "mcp-everything_*": "allow",
     "angular-cli_*": "allow",
     "playwright_*": "allow",
+    "context7_*": "allow",
     "memory-bank_*": "allow"
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.46.0",
+  "version": "1.48.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",
   "bin": {
@@ -38,6 +38,7 @@
     "url": "https://github.com/abarcenas29/ai-workflow-template/issues"
   },
   "homepage": "https://github.com/abarcenas29/ai-workflow-template#readme",
+  "//": "Never add AGENTS.project.md or opencode.json to files: both are scaffolded create-if-absent at the consumer root and must not ship from the package.",
   "files": [
     "bin/",
     ".agents/",
@@ -49,6 +50,7 @@
     ".husky/",
     "memory-bank/.vocabulary.json",
     "AGENTS.md",
+    ".prettierignore",
     "opencode.mcp.example.json",
     "skills-lock.json",
     ".husky/post-merge",