@abarcenas/ai-workflow-template 1.46.0 → 1.48.0

package/.agents/config/README.md

@@ -27,10 +27,10 @@ the second calls `grilling` and `domain-modeling` together.
 
 ## Scope agent
 
-`.opencode/agents/scope.agent.md` is the front door for underspecified feature requests. It
+`.opencode/agents/scope.md` is the front door for underspecified feature requests. It
 runs grilling in rounds against a draft file, emits the current frontier as numbered questions,
 and finishes by writing a spike document at `docs/spike-<feature>.md` — the input
-`researcher.agent.md` already expects.
+`researcher.md` already expects.
 
 It never builds or runs code. When a question needs a prototype it emits
 `prototype needed: <question>`, and the orchestrator delegates the work to `coder` (logic) or

package/.agents/instructions/agent.instructions.md

@@ -1,6 +1,6 @@
 ---
 description: "Guidelines for creating custom agent files for opencode"
-applyTo: "**/*.agent.md"
+applyTo: "**/agents/**/*.md"
 ---
 
 # Custom Agent File Guidelines
@@ -11,7 +11,7 @@ Instructions for creating effective and maintainable custom agent files that pro
 
 - Target audience: Developers creating custom agents for opencode
 - File format: Markdown with YAML frontmatter
-- File naming convention: lowercase with hyphens (e.g., `test-specialist.agent.md`)
+- File naming convention: lowercase with hyphens (e.g., `test-specialist.md`)
 - Location: `.opencode/agents/` directory (repository-level)
 - Purpose: Define specialized agents with tailored expertise, tools, and instructions for specific tasks
 - Official documentation: [opencode.ai](https://opencode.ai)
@@ -39,7 +39,7 @@ tools: ["Read", "Edit", "Grep"]
 #### **name** (OPTIONAL)
 
 - Display name for the agent
-- If omitted, defaults to filename (without `.md` or `.agent.md`)
+- If omitted, defaults to filename (without `.md`)
 - Use title case and be descriptive
 - Example: `'Testing Specialist'`
 
@@ -123,7 +123,7 @@ The recommended approach is **prompt-based orchestration**:
 
 - The orchestrator defines a step-by-step workflow in natural language.
 - Each step is delegated to a specialized agent.
-- The orchestrator passes only the essential context (e.g., base path, identifiers) and requires each sub-agent to read its own `.agent.md` spec for tools/constraints.
+- The orchestrator passes only the essential context (e.g., base path, identifiers) and requires each sub-agent to read its own `.md` spec for tools/constraints.
 
 ### How It Works
 
@@ -136,7 +136,7 @@ tools: ["Read", "Edit", "Grep", "Task"]
 2. For each step, invoke a sub-agent by providing:
 
 - **Agent name** (the identifier users select/invoke)
-- **Agent spec path** (the `.agent.md` file to read and follow)
+- **Agent spec path** (the `.md` file to read and follow)
 - **Minimal shared context** (e.g., base path, project name, log file)
 
 ### Prompt Pattern (Recommended)
@@ -147,7 +147,7 @@ Use a consistent "wrapper prompt" for every step so sub-agents behave predictabl
 This phase must be performed as the agent "<AGENT_NAME>" defined in "<AGENT_SPEC_PATH>".
 
 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_NAME>" with base path: "<BASE_PATH>".
 - Perform the necessary reads/writes under this base path.
 - Return a clear summary (actions taken + files produced/modified + issues).
@@ -191,7 +191,7 @@ Structure each step invocation with:
 ```text
 Step 1: Transform raw input data
 Agent: data-processor
-Spec: .opencode/agents/data-processor.agent.md
+Spec: .opencode/agents/data-processor.md
 Context: projectName, basePath
 Input: basePath/raw/
 Output: basePath/processed/
@@ -199,7 +199,7 @@ Expected: write basePath/processed/summary.md
 
 Step 2: Analyze processed data (depends on Step 1 output)
 Agent: data-analyst
-Spec: .opencode/agents/data-analyst.agent.md
+Spec: .opencode/agents/data-analyst.md
 Context: projectName, basePath
 Input: basePath/processed/
 Output: basePath/analysis/
@@ -363,10 +363,10 @@ When invoking a sub-agent, pass all context through descriptive instructions in
 Example (prompt template):
 
 ```text
-This phase must be performed as the agent "documentation-writer" defined in ".opencode/agents/documentation-writer.agent.md".
+This phase must be performed as the agent "documentation-writer" defined in ".opencode/agents/documentation-writer.md".
 
 IMPORTANT:
-- Read and apply the entire .agent.md spec.
+- Read and apply the entire agent spec file.
 - Project: [project name]
 - Base path: [base path]
 - Input: [input path]
@@ -389,24 +389,24 @@ Example of a simple orchestrator that validates code through multiple specialize
    - Repository name, PR number
    - Base path
 
-2. Invoke specialized agents sequentially (each agent reads its own `.agent.md` spec):
+2. Invoke specialized agents sequentially (each agent reads its own `.md` spec):
 
 ```text
 Step 1: Security Review
 Agent: security-reviewer
-Spec: .opencode/agents/security-reviewer.agent.md
+Spec: .opencode/agents/security-reviewer.md
 Context: repository name, PR number, base path
 Output: security-review.md
 
 Step 2: Test Coverage
 Agent: test-coverage
-Spec: .opencode/agents/test-coverage.agent.md
+Spec: .opencode/agents/test-coverage.md
 Context: repository name, PR number, base path
 Output: coverage-report.md
 
 Step 3: Aggregate
 Agent: review-aggregator
-Spec: .opencode/agents/review-aggregator.agent.md
+Spec: .opencode/agents/review-aggregator.md
 Context: repository name, PR number, base path
 Output: final-review.md
 ```
@@ -462,7 +462,7 @@ Use consistent variable naming conventions:
 
 ### Naming Conventions
 
-- Use lowercase with hyphens: `test-specialist.agent.md`
+- Use lowercase with hyphens: `test-specialist.md`
 - Name should reflect agent purpose
 - Filename becomes default agent name (if `name` not specified)
 - Allowed characters: `.`, `-`, `_`, `a-z`, `A-Z`, `0-9`
@@ -493,7 +493,7 @@ Use consistent variable naming conventions:
 - [ ] Filename follows lowercase-with-hyphens convention
 - [ ] File placed in correct directory (`.opencode/agents/`)
 - [ ] Filename uses only allowed characters
-- [ ] File extension is `.agent.md`
+- [ ] File extension is `.md`
 
 ### Quality Assurance
 

package/.agents/instructions/context7.instructions.md

@@ -107,3 +107,43 @@ If Context7 cannot find a reliable source:
 
 - Never request or echo API keys. If configuration requires a key, instruct storing it in environment variables.
 - Treat retrieved docs as **helpful but not infallible**; for security-sensitive code, prefer official vendor docs and add an explicit verification step.
+
+## Configuration & troubleshooting (opencode)
+
+opencode substitutes only two forms inside config files:
+
+- `{env:VARIABLE_NAME}` — an **unset variable becomes an empty string**, which fails silently
+- `{file:path/to/file}` — file contents; `~` is supported
+
+It does **not** understand shell-style `$VARIABLE`. Writing `"CONTEXT7_API_KEY": "$CONTEXT7_TOKEN"` sends the literal text `$CONTEXT7_TOKEN` as the header value. The server accepts it at `initialize` and only rejects it at the first tool call, so the MCP reports as *connected* while every tool fails with an invalid-key error.
+
+A valid remote entry:
+
+```json
+"context7": {
+  "type": "remote",
+  "url": "https://mcp.context7.com/mcp",
+  "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_TOKEN}" },
+  "enabled": true
+}
+```
+
+### Local servers differ in shape
+
+`McpLocalConfig` requires `command` to be an **array** and the env object to be named `environment`. There is no `args` key and no `env` key — using either makes opencode log `skipped malformed recognized value` and the server never appears in the tool list at all.
+
+```json
+"github": {
+  "type": "local",
+  "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
+  "environment": { "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}" },
+  "enabled": true
+}
+```
+
+### Diagnosing a dead server
+
+1. Test the credential directly before touching config — `curl` the endpoint, or run the CLI that owns the token. This separates "bad key" from "key never arrived".
+2. Read `~/.local/share/opencode/log/opencode.log` and look for `mcp connected server=<name>` versus `skipped malformed`.
+3. Prefer `{file:~/.config/opencode/secrets/<name>}` when opencode may not be launched from an interactive shell: variables exported in `~/.zshrc` are visible only to interactive zsh sessions, so GUI-launched sessions see nothing.
+4. A private-repo 404 (GitHub) or a 422 from search usually means the MCP is running **anonymous**, not that the resource is missing.

package/.agents/instructions/learned-knowledge.instructions.md

@@ -577,3 +577,21 @@
 - **coder (index audits)**: Enumerate all mutating paths — create, update, shrink, delete-source, failure — then assert the same invariant helper on each. The bug was in the paths that had never been tested, not in the one that had.
 - **deployer**: This was a **follow-up fix** to a bug deliberately recorded as open in commit `308c90f`; the tracker entry must explicitly mark that follow-up **resolved** so the audit trail does not keep an open defect that no longer exists. Re-run all three gates before and after, stage only the enumerated files, and use `SKIP_BUMP=1` so the fix does not bump the minor version.
 - **all agents (knowledge retrieval)**: `memory_search` returned "No results found. The index may be empty"; `knowledgebase_search` was **not executed** (PG vector unavailable — `DATABASE_URL` not configured). Both reported as skipped/unavailable, neither retried, neither treated as a task failure.
+
+## Session: 2026-10-25 — Project-Owned Layer for Sync (ownership before force; formatter freeze hazard)
+
+**Pipeline:** implementer → coder → reviewer (round 1: APPROVE WITH CHANGES) → coder → reviewer (round 2: BLOCK) → coder (round 3 fixes) → tracker
+**Scope:** `scripts/sync.js`, `scripts/sync-unit.test.js`, `.prettierignore`, `AGENTS.md`, `README.md`, `package.json`, `opencode.mcp.example.json`
+**Verification:** 26 files / **790 tests**, 0 failures; coverage **96.88 / 94.9 / 96.87 / 97.09**; `npm pack --dry-run` ships `.prettierignore` and excludes `AGENTS.project.md` and `opencode.json`; consumer repos untouched (apmc-cms: only its three pre-existing modified files; apmc-v2 clean).
+
+**New knowledge:**
+- **Sync mechanics, decided once and recorded here:** the overwrite policy is **hash-equality**; a file whose hash does not match is skipped **permanently** and only refreshes if the consumer writes it again. `--force` is destructive with **no backup**. Prune is **opt-in** and is never passed by the setup command. `opencode.json` looked managed (it sat in `rootFiles` at HEAD) but was excluded from the tarball with no manifest key, so it was effectively scaffold-once — **verify tarball + manifest key + copy loop before assuming any file is managed.**
+- **Design pattern that worked:** check ownership **before** the `forceOverwrite || isUntouched` branch, and short-circuit prune on ownership **before** hashing. A guard placed after either decision point does not hold — the file is already copied or already queued for deletion. One exported `Set` matching channel-agnostically (root name also protects nested names) is deliberately over-conservative and easier to keep correct than four parallel checks.
+- **Testing pattern that failed:** writing the shipped file verbatim as the test fixture only proved the parser agreed with itself — it passed while the detector was wrong in both directions. What caught it was a **table-driven matrix with both outcomes asserted** (false alarm *and* false all-clear) plus **parent-directory-protected, negated-hole, and real-consumer end-to-end fixtures**. A detector of "is the user's config adequate" needs both directions, or the vacuous case hides the bug.
+- **Formatter hazard (consumer-fatal):** a repo-wide Prettier run over sync-managed files rewrites their hashes and is by itself sufficient to **permanently freeze** a consumer's updates. `.prettierignore` must be established **before** formatting, not added after the damage. Ship it, scaffold it if absent, and warn once when an existing one is inadequate.
+
+**Agent tuning notes:**
+- **implementer / coder**: asking an implementing agent to **pause when a heuristic exceeds a stated complexity threshold** produced an honest escalation instead of a silently wrong heuristic. Worth repeating for any "detect whether the user's config is adequate" feature: state the threshold up front and treat pausing as success, not failure.
+- **reviewer (two-round shape)**: round 1 caught missing user-facing coverage; round 2 blocked the *new* mechanism for being wrong in both directions. A fix that introduces a heuristic deserves a dedicated review pass — reviewing it as part of the original change under-weights it.
+- **coder (docs for honest gaps)**: protect-but-don't-honour (`.agents-sync-ignore`) must be stated plainly in the README and in code comments. Shipping the storage without the semantics is acceptable only when it is impossible to mistake for working.
+- **all agents (knowledge retrieval)**: `memory_search` executed (cwd-scoped to this repo); `knowledgebase_search` **NOT executed** (PG vector unavailable — `DATABASE_URL` not configured). Neither retried nor treated as a task failure.

package/.agents/instructions/memory-bank.instructions.md

@@ -136,10 +136,10 @@ All `memory-bank/**/*.md` files must have YAML frontmatter for search indexing.
 
 Scope comes before planning. Underspecified work enters through the `scope` agent; planning starts only once the request is narrowed.
 
-1. **Scope first** — for an underspecified request, the front door is the `scope` agent (`.opencode/agents/scope.agent.md`). It runs grilling rounds against a single draft file, then writes a terminal spike document at `docs/spike-<feature>.md`.
-2. **Hand the spike to research** — that spike document is the input `researcher.agent.md` expects; pass its path as the required spike argument.
+1. **Scope first** — for an underspecified request, the front door is the `scope` agent (`.opencode/agents/scope.md`). It runs grilling rounds against a single draft file, then writes a terminal spike document at `docs/spike-<feature>.md`.
+2. **Hand the spike to research** — that spike document is the input `researcher.md` expects; pass its path as the required spike argument.
 3. **Continue the pipeline** — after research (or directly, when no research is needed), the work continues to `implementer`, `architect`, or `coder`, following the recommended next step recorded in the spike.
-4. **Deep planning is optional** — `plan.agent.md` remains available as an optional deep-planning mode for work that is already scoped. It is demoted in the default flow, not removed or deprecated.
+4. **Deep planning is optional** — `planner.md` remains available as an optional deep-planning mode for work that is already scoped. It is demoted in the default flow, not removed or deprecated.
 
 When scope runs, record the spike document in the memory bank (a task entry in `tasks/` and/or `activeContext.md`) before implementation planning begins, so the settled and deferred decisions survive a session reset.
 

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

@@ -1,11 +1,10 @@
 ---
 description: "System architecture and design specialist. Designs component architecture, data flow, module boundaries, and technical strategy. Produces architecture decision records and design documents."
-name: "Architect - System Design"
-permission:
-  read: allow
-  search: 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 }
 ---
 
 # Architect - System Design

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

@@ -1,13 +1,9 @@
 ---
 description: "Production code implementation specialist. Writes clean, maintainable, well-tested code following project conventions. Implements features, fixes bugs, and refactors existing code."
-name: "Coder - Implementation"
-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 }
 ---
 
 # Coder - Implementation

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

@@ -1,14 +1,9 @@
 ---
 description: "Deployment and release engineering specialist. Handles CI/CD configuration, deployment scripts, release management, infrastructure as code, and environment setup."
-name: "Deployer - Release Engineering"
-permission:
-  read: allow
-  search: allow
-  edit: allow
-  execute: allow
-  "github/*": allow
-  "memory-bank/*": allow
-  "knowledgebase/*": allow
+mode: all
+permissions:
+  - { action: edit,  resource: "*",    effect: allow }
+  - { action: shell, resource: "*",    effect: allow }
 ---
 
 # Deployer - Release Engineering

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

@@ -1,11 +1,10 @@
 ---
 description: "UI/UX design specialist. Handles component layout, visual styling, responsive design, design systems, and user experience considerations."
-name: "Designer - UI/UX"
-permission:
-  read: "allow"
-  search: "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 }
 ---
 
 # Designer - UI/UX

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

@@ -1,12 +1,9 @@
 ---
 description: "Browser debugging and exploration specialist. Inspects pages, analyzes network, takes screenshots, and investigates UI behavior using Chrome DevTools. Read-only — no code or test creation."
-name: "E2E Tester - Browser Automation"
-permission:
-  read: allow
-  search: allow
-  "chrome-devtools/*": allow
-  "memory-bank/*": allow
-  "knowledgebase/*": allow
+mode: all
+permissions:
+  - { action: edit,  resource: "*",    effect: deny }
+  - { action: shell, resource: "*",    effect: deny }
 ---
 
 # E2E Tester - Browser Automation

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

@@ -1,13 +1,9 @@
 ---
 description: "Implementation planning specialist. Translates architecture and design documents into detailed, actionable implementation plans with task breakdowns, file-level specifications, and execution ordering."
-name: "Implementer - Implementation Planning"
-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 }
 ---
 
 # Implementer - Implementation Planning

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

@@ -1,13 +1,10 @@
 ---
 description: "Stripped-down feature pipeline orchestrator that runs implementer, designer, coder, and tracker sequentially. Bootstraps architecture context, supports step-by-step confirmation, logs progress, and persists lessons learned."
-name: "Feature Pipeline"
-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 }
 ---
 
 # Feature Pipeline
@@ -26,10 +23,10 @@ You are a lightweight orchestration agent that runs a fixed sequential pipeline:
 
 | Step | Role | Agent File | subagent_type | Purpose |
 |---|---|---|---|---|---|
-| 1 | implementer | `implementer.agent.md` | `implementer` | Translate architecture/design into detailed implementation plans |
-| 2 | designer | `designer.agent.md` | `designer` | UI/UX design specs, component layout — no code |
-| 3 | coder | `coder.agent.md` | `coder` | Write production code, implement features |
-| 4 | tracker | `tracker.agent.md` | `tracker` | Document completed work to `docs/tracker-log.md` |
+| 1 | implementer | `implementer.md` | `implementer` | Translate architecture/design into detailed implementation plans |
+| 2 | designer | `designer.md` | `designer` | UI/UX design specs, component layout — no code |
+| 3 | coder | `coder.md` | `coder` | Write production code, implement features |
+| 4 | tracker | `tracker.md` | `tracker` | Document completed work to `docs/tracker-log.md` |
 
 ## Workflow
 
@@ -40,12 +37,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.
@@ -96,7 +93,7 @@ For each step:
 This phase must be performed as the agent "{agent_name}" defined in ".opencode/agents/{agent_file}".
 
 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}".
 - Perform the necessary reads/writes under this base path.
 - Previous step context: {previous_step_summary}
@@ -129,10 +126,10 @@ When the pipeline reaches the "coder" step and the latest implementer plan has p
    b. Log: `"Batch {letter}: launching {N} parallel coder tasks — {task_ids}"`
    c. Launch **one Task tool invocation per 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).
       - Work on "Implement task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
       - Perform the necessary reads/writes under this base path.
       - Previous step context: {previous_step_summary}
@@ -199,12 +196,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/orchestrator/{orchestrator.agent.md → orchestrator.md}

@@ -1,18 +1,10 @@
 ---
 description: "Master orchestration agent that dynamically builds and executes multi-step development pipelines. Analyzes user requests, selects the right sub-agents, delegates work with context, and tracks progress through a shared log. Supports both auto-execute and step-by-step confirmation modes."
-name: "Orchestrator - Multi-Agent Workflow"
-permission:
-  search: allow
-  read: allow
-  agent: allow
-  web: allow
-  todo: allow
-  "ddg-search/*": allow
-  "context7/*": allow
-  "github/*": allow
-  "chrome-devtools/*": 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 }
 ---
 
 # Orchestrator - Multi-Agent Workflow
@@ -31,17 +23,17 @@ You are a master orchestration agent that coordinates specialized sub-agents to
 
 | Role | Agent File | subagent_type | Typical Tools | When to Deploy |
 |---|---|---|---|---|
-| scope | `scope.agent.md` | `scope` | read, search, edit, skill, question (no `execute` — never builds or runs anything) | Underspecified request, vague or unmeasurable success criteria, unknown boundaries, or an explicit request to narrow scope; runs the scoping interview only — never designs or builds |
-| researcher | `researcher.agent.md` | `researcher` | read, search, web, ddg-search/*, context7/* (read-only — no edit, no execute) | Technical unknowns, library evaluation, spike investigation |
-| architect | `architect.agent.md` | `architect` | read, search (no edit — design docs only) | System design, component architecture, data flow planning |
-| implementer | `implementer.agent.md` | `implementer` | read, search, edit, execute | Translating plans into actionable implementation steps |
-| designer | `designer.agent.md` | `designer` | read, search (no edit — design specs only) | UI/UX design, component layout, styling specs |
-| coder | `coder.agent.md` | `coder` | read, search, edit, execute | Writing production code, implementing features |
-| unit-tester | `unit-tester.agent.md` | `unit-tester` | read, search, edit, execute (test files only — *.spec.ts, *.test.ts) | Unit tests, integration tests, test coverage |
-| e2e-tester | `e2e-tester.agent.md` | `e2e-tester` | read, search, chrome-devtools/* | Debugging, exploration, page inspection via Chrome DevTools |
-| reviewer | `reviewer.agent.md` | `reviewer` | read, search, github/* | Code review, security audit, quality gates |
-| deployer | `deployer.agent.md` | `deployer` | read, search, edit, execute, github/* | CI/CD configuration, deployment scripts, release management |
-| tracker | `tracker.agent.md` | `tracker` | read, search | Doc recording — runs after pipeline to log finished work to docs/tracker-log.md |
+| scope | `scope.md` | `scope` | read, search, edit, skill, question (no `execute` — never builds or runs anything) | Underspecified request, vague or unmeasurable success criteria, unknown boundaries, or an explicit request to narrow scope; runs the scoping interview only — never designs or builds |
+| researcher | `researcher.md` | `researcher` | read, search, web, ddg-search/*, context7/* (read-only — no edit, no execute) | Technical unknowns, library evaluation, spike investigation |
+| architect | `architect.md` | `architect` | read, search (no edit — design docs only) | System design, component architecture, data flow planning |
+| implementer | `implementer.md` | `implementer` | read, search, edit, execute | Translating plans into actionable implementation steps |
+| designer | `designer.md` | `designer` | read, search (no edit — design specs only) | UI/UX design, component layout, styling specs |
+| coder | `coder.md` | `coder` | read, search, edit, execute | Writing production code, implementing features |
+| unit-tester | `unit-tester.md` | `unit-tester` | read, search, edit, execute (test files only — *.spec.ts, *.test.ts) | Unit tests, integration tests, test coverage |
+| e2e-tester | `e2e-tester.md` | `e2e-tester` | read, search, chrome-devtools/* | Debugging, exploration, page inspection via Chrome DevTools |
+| reviewer | `reviewer.md` | `reviewer` | read, search, github/* | Code review, security audit, quality gates |
+| deployer | `deployer.md` | `deployer` | read, search, edit, execute, github/* | CI/CD configuration, deployment scripts, release management |
+| tracker | `tracker.md` | `tracker` | read, search | Doc recording — runs after pipeline to log finished work to docs/tracker-log.md |
 
 ## Workflow
 
@@ -52,12 +44,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.
@@ -137,7 +129,7 @@ For every scope round, the orchestrator must:
 One delegation is one round. Delegate the round with these inputs:
 
 ```text
-Agent: "Scope - Feature Scoping" (.opencode/agents/scope.agent.md)
+Agent: "Scope - Feature Scoping" (.opencode/agents/scope.md)
 work_unit: {feature}
 basePath: {basePath}
 draftPath: docs/spike-<feature>.draft.md
@@ -180,7 +172,7 @@ For each step in the pipeline:
 This phase must be performed as the agent "{agent_name}" defined in ".opencode/agents/{agent_file}".
 
 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}".
 - Perform the necessary reads/writes under this base path.
 - Previous step context: {previous_step_summary}
@@ -211,10 +203,10 @@ When the pipeline reaches the "coder" step and the implementer's summary include
    b. Log: `"Batch {letter}: launching {N} parallel coder tasks — {task_ids}"`
    c. Launch **one Task tool invocation per 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).
       - Work on "Implement task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
       - Perform the necessary reads/writes under this base path.
       - Previous step context: {previous_step_summary}
@@ -239,10 +231,10 @@ After the pipeline finishes executing (all steps complete or a required step fai
 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.
@@ -300,12 +292,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: