feat(mcp): make browser/crawler MCP servers conditional on project.yaml

[JustAGhosT]

Summary

• Adds buildBrowserTestingVars() to var-builders.mjs — derives usesPlaywright and usesBrowser from testing.e2e in project.yaml
• Wires new vars into synchronize.mjs alongside existing heuristics
• Updates templates/mcp/servers.json: puppeteer/playwright/storybook-crawler are now conditional ({{#if usesPlaywright}}, {{#if usesBrowser}}, {{#if hasStorybook}}) — omitted when unused

Test plan

• Verify a project with testing.e2e: [playwright] generates a servers.json with the playwright MCP entry
• Verify a project with testing.e2e: [cypress] generates puppeteer entry (not playwright)
• Verify a project with no e2e testing generates neither
• Verify hasStorybook: true still generates storybook-crawler entry

Closes #503

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Detects browser testing frameworks (Playwright, Cypress, Puppeteer, WebDriverIO) from project config and exposes flags.
  • MCP server entries for Playwright, Puppeteer and Storybook crawler are now included only when needed.

• Documentation

  • Regeneration metadata and tooling references updated to use Retort across docs and templates.
  • Skill metadata timestamps updated.

[blocksorg]

Mention Blocks like a regular teammate with your question or request:

@blocks review this pull request
@blocks make the following changes ...
@blocks create an issue from what was mentioned in the following comment ...
@blocks explain the following code ...
@blocks are there any security or performance concerns?

Run @blocks /help for more information.

Workspace settings | Disable this message

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[github-actions]

Retort Source Change Detected

This PR modifies files in the Retort source directories:

• .agentkit/templates/ — output templates
• .agentkit/spec/ — YAML specifications
• .agentkit/engines/ — sync engine code
• .agentkit/overlays/ — per-repo customizations
• .agentkit/bin/ — CLI scripts

These are the upstream source-of-truth for all generated AI tool configs.

Review checklist

• Changes are intentional and not accidental AI agent modifications
• Spec schema validation passes (pnpm --dir .agentkit agentkit:spec-validate)
• Sync produces expected output (pnpm --dir .agentkit agentkit:sync)
• No secrets or credentials in template variables
• Breaking changes documented in an ADR

AI agents: Do not modify these files directly. Propose changes in a dedicated PR.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a browser-testing var builder and wires its flags into the sync flow so MCP server template rendering can conditionally include Playwright, Puppeteer, or Storybook crawler entries based on project testing and Storybook settings.

Changes

Cohort / File(s)	Summary
Browser testing var builder .agentkit/engines/node/src/var-builders.mjs	New exported buildBrowserTestingVars(projectSpec) that normalizes projectSpec.testing.e2e and returns { usesPlaywright, usesBrowser }.
Sync integration synchronize.mjs .agentkit/engines/node/src/synchronize.mjs	Imports and calls buildBrowserTestingVars(projectSpec) during sync; sets vars.usesPlaywright and vars.usesBrowser on template variables.
MCP servers template .agentkit/templates/mcp/servers.json	Converted to conditional Handlebars fragments: include mcpServers.playwright only when usesPlaywright, mcpServers.puppeteer when usesBrowser, and mcpServers.storybook-crawler when hasStorybook; removed unconditional puppeteer entry.
Repo metadata & docs multiple *.md, .editorconfig, .prettierrc, .github/*, .vscode/settings.json, AGENT_BACKLOG.md, etc.	Non-functional updates: generator/regeneration header changes (AgentKit Forge → Retort), minor formatting/metadata edits, and a large backlog rewrite; no runtime code changes.

Sequence Diagram(s)

sequenceDiagram
    participant ProjectSpec as ProjectSpec
    participant VarBuilder as buildBrowserTestingVars
    participant Sync as Synchronize
    participant Template as MCP Template
    participant Output as Generated servers.json

    ProjectSpec->>VarBuilder: provide testing.e2e, storybook, frontend flags
    VarBuilder->>VarBuilder: normalize e2e entries\ndetect playwright vs other browsers
    VarBuilder-->>Sync: return { usesPlaywright, usesBrowser }
    Sync->>Sync: assign vars.usesPlaywright\nvars.usesBrowser (plus hasStorybook)
    Sync->>Template: render servers.json with vars
    Template->>Template: conditionally include\nplaywright / puppeteer / storybook-crawler
    Template->>Output: produce final servers.json

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat(config): add .retortconfig — agent remapping and opt-in feature flags v1 #479 — Modifies the same engine sync pipeline (synchronize.mjs → runSync) to attach extra template variables.
• refactor(sync): extract spec-loader, overlay-resolver, var-builders, platform-syncer (Steps 3-6) #484 — Earlier var-builders refactor that introduced related helpers; this PR extends that work with browser-testing vars.
• feat(cli): add run subcommand for agent task dispatch #493 — Also updates runSync/template-variable handling in synchronize.mjs; overlaps with this wiring change.

Poem

🐰
I hopped through vars to sniff the test,
Playwright or Puppeteer — I know which quest,
Storybook hums where components rest,
Templates now pick what suits them best,
A little rabbit cheers this conditional fest.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR includes significant out-of-scope changes: numerous documentation files updated with Retort/agentkit-forge branding changes, skill metadata updates, .editorconfig modifications, and AGENT_BACKLOG.md restructuring unrelated to the MCP server conditional logic.	Separate the MCP server conditional changes into a focused PR, and move documentation/branding/metadata updates to a separate commit or PR.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately reflects the main change: making browser/crawler MCP servers conditional based on project.yaml configuration.
Linked Issues check	✅ Passed	The PR implements all core requirements from issue #503: adds buildBrowserTestingVars() to derive usesPlaywright/usesBrowser flags from testing.e2e, wires them into synchronize.mjs, and converts servers.json to a Handlebars template with conditional MCP server entries.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/conditional-mcp-servers

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 OpenGrep (1.16.5)

.vscode/settings.json

┌──────────────┐
│ Opengrep CLI │
└──────────────┘

�[32m✔�[39m �[1mOpengrep OSS�[0m
�[32m✔�[39m Basic security coverage for first-party code vulnerabilities.

�[1m Loading rules from local config...�[0m

.agentkit/templates/mcp/servers.json

┌──────────────┐
│ Opengrep CLI │
└──────────────┘

�[32m✔�[39m �[1mOpengrep OSS�[0m
�[32m✔�[39m Basic security coverage for first-party code vulnerabilities.

�[1m Loading rules from local config...�[0m

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.agentkit/engines/node/src/synchronize.mjs:
- Around line 57-58: You modified generated sync engine exports (the identifiers
buildBrowserTestingVars and buildCollaboratorsSection) inside the engine file;
revert those edits and do not change files under the .agentkit/engines/ path.
Instead, implement the intended change in the upstream generator/template that
produces this file (or in an overlay) — update the template or overlay that
defines/export these symbols (buildBrowserTestingVars,
buildCollaboratorsSection) so the generated synchronize.mjs includes the change,
then re-run the generation to produce the correct engine artifact.

In @.agentkit/templates/mcp/servers.json:
- Line 8: The "storybook-crawler" entry in the generated template is incorrect
and must not be edited in .agentkit/templates/mcp/servers.json; instead update
the generator spec under .agentkit/spec that defines the "storybook-crawler"
server entry so the template can be regenerated. In that spec, replace the
non-existent package "@chromatic-com/storybook-mcp-server" with a valid npm
package (or add a note clarifying the actual Storybook MCP implementation
required), then run the template generation step to produce an updated
servers.json; ensure the spec references the exact symbol "storybook-crawler"
and the corrected package name so the generated template is consistent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d00f24a8-fa63-40a6-a7ef-c62a19f0f8fc

📥 Commits

Reviewing files that changed from the base of the PR and between cadad02 and 3922ea5.

📒 Files selected for processing (3)

• .agentkit/engines/node/src/synchronize.mjs
• .agentkit/engines/node/src/var-builders.mjs
• .agentkit/templates/mcp/servers.json

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Do not modify sync engine files directly in this repo path.

This PR edits .agentkit/engines/** directly (Line 57), which violates the repository’s generation workflow guardrails and can cause drift policy failures.

As per coding guidelines, "AI agents must never directly modify files in .agentkit/templates/, .agentkit/engines/, .agentkit/overlays/, or .agentkit/bin/ directories as they contain upstream sync engine, templates, and CLI scripts".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.agentkit/engines/node/src/synchronize.mjs around lines 57 - 58, You
modified generated sync engine exports (the identifiers buildBrowserTestingVars
and buildCollaboratorsSection) inside the engine file; revert those edits and do
not change files under the .agentkit/engines/ path. Instead, implement the
intended change in the upstream generator/template that produces this file (or
in an overlay) — update the template or overlay that defines/export these
symbols (buildBrowserTestingVars, buildCollaboratorsSection) so the generated
synchronize.mjs includes the change, then re-run the generation to produce the
correct engine artifact.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify package availability on npm registry.
curl -s https://registry.npmjs.org/@chromatic-com%2Fstorybook-mcp-server | jq -r '."dist-tags".latest // "NOT_FOUND"'
curl -s https://registry.npmjs.org/@playwright%2Fmcp | jq -r '."dist-tags".latest // "NOT_FOUND"'
curl -s https://registry.npmjs.org/@modelcontextprotocol%2Fserver-puppeteer | jq -r '."dist-tags".latest // "NOT_FOUND"'

Repository: phoenixvc/retort

Length of output: 86

---

🏁 Script executed:

# Check if the file is marked as generated
head -20 .agentkit/templates/mcp/servers.json

# Look for spec files that might define MCP servers
find .agentkit/spec -name "*servers*" -o -name "*mcp*" 2>/dev/null | head -20

# Search for any documentation about Storybook requirement
rg -i "storybook" .agentkit/spec --type json --type yaml --type md -A 2 -B 2

# Check git history for context on this change (recent commits)
git log --oneline -20 -- .agentkit/templates/mcp/servers.json

Repository: phoenixvc/retort

Length of output: 2708

---

Do not edit this template file directly; update the spec instead.

File .agentkit/templates/mcp/servers.json is in a protected directory. Per coding guidelines, template files must not be modified directly. Changes must be made in .agentkit/spec/ and regenerated.

Additionally, the package @chromatic-com/storybook-mcp-server does not exist on the npm registry. If Storybook MCP support is required, the spec and template must reference an available package or clarify the actual requirement.

🧰 Tools

🪛 Biome (2.4.9)

[error] 8-8: expected , but instead found {

(parse)

---

[error] 8-8: Expected a property but instead found '{'.

(parse)

---

[error] 8-8: unexpected character ~

(parse)

---

[error] 8-8: unexpected character /

(parse)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.agentkit/templates/mcp/servers.json at line 8, The "storybook-crawler"
entry in the generated template is incorrect and must not be edited in
.agentkit/templates/mcp/servers.json; instead update the generator spec under
.agentkit/spec that defines the "storybook-crawler" server entry so the template
can be regenerated. In that spec, replace the non-existent package
"@chromatic-com/storybook-mcp-server" with a valid npm package (or add a note
clarifying the actual Storybook MCP implementation required), then run the
template generation step to produce an updated servers.json; ensure the spec
references the exact symbol "storybook-crawler" and the corrected package name
so the generated template is consistent.

[github-actions]

Merge Conflict Detected

This branch (feat/conditional-mcp-servers) has merge conflicts with dev.

Auto-resolvable files

These will be handled automatically by scripts/resolve-merge.sh:

(none)

Manual resolution required

(none — all conflicts are auto-resolvable!)

How to resolve

Option 1 — Use the resolution script:

git checkout feat/conditional-mcp-servers
scripts/resolve-merge.sh dev

Option 2 — Manual merge:

git checkout feat/conditional-mcp-servers
git merge origin/dev
# resolve conflicts, then:
git add -A && git commit

---

Posted by Merge Conflict Detection workflow

[coderabbitai]

♻️ Duplicate comments (1)

.agentkit/templates/mcp/servers.json (1)

5-8: ⚠️ Potential issue | 🟠 Major

Move this change into .agentkit/spec/ and regenerate outputs instead of editing this template directly.

This file is in a protected generated/template path. Please apply the MCP conditional logic in the corresponding .agentkit/spec/ source and regenerate with pnpm --dir .agentkit agentkit:sync before merging.

As per coding guidelines, "AI agents must never directly modify files in .agentkit/templates/, .agentkit/engines/, .agentkit/overlays/, or .agentkit/bin/ directories as they contain upstream sync engine, templates, and CLI scripts".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.agentkit/templates/mcp/servers.json around lines 5 - 8, The change to add
MCP server entries should not be edited directly in the generated template
`.agentkit/templates/mcp/servers.json`; instead, update the source spec in
`.agentkit/spec/` to include the conditional MCP entries (the fetch entry and
the conditional blocks for usesPlaywright, usesBrowser/puppeteer, and
hasStorybook/storybook-crawler), then regenerate the templated outputs by
running the agentkit sync command (pnpm --dir .agentkit agentkit:sync) so the
updated `servers.json` is produced correctly from the spec.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In @.agentkit/templates/mcp/servers.json:
- Around line 5-8: The change to add MCP server entries should not be edited
directly in the generated template `.agentkit/templates/mcp/servers.json`;
instead, update the source spec in `.agentkit/spec/` to include the conditional
MCP entries (the fetch entry and the conditional blocks for usesPlaywright,
usesBrowser/puppeteer, and hasStorybook/storybook-crawler), then regenerate the
templated outputs by running the agentkit sync command (pnpm --dir .agentkit
agentkit:sync) so the updated `servers.json` is produced correctly from the
spec.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 000ab04c-352f-43e7-a58b-deff1302ec07

📥 Commits

Reviewing files that changed from the base of the PR and between 3922ea5 and 1d1f614.

📒 Files selected for processing (1)

• .agentkit/templates/mcp/servers.json

[coderabbitai]

Actionable comments posted: 8

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/agents/agent-team-matrix.md (1)

1-340: ⚠️ Potential issue | 🟠 Major

This file change appears unrelated to the PR objectives.

The PR objectives focus on making MCP browser/crawler servers conditional based on project.yaml testing configuration. However, this file documents agent/team relationship matrices and has been regenerated with:

• Rebranding from "AgentKit Forge" to "Retort" (line 3)
• Reordered agent membership tables
• Updated dependency and notification matrices
• Recalculated analytics

These changes have no apparent connection to MCP server configuration logic. Including unrelated regenerated documentation increases review complexity and merge risk.

Recommendation: If the rebranding and matrix regeneration are intentional, please move them to a separate PR with appropriate objectives. If they were included accidentally (e.g., from running agentkit:sync during development), please remove this file from the PR and commit only the MCP-related changes.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/agents/agent-team-matrix.md` around lines 1 - 340, This change
regenerates the "Agent/Team Relationship Matrix" documentation (rebranding to
"Retort" and wide matrix/table diffs) which is unrelated to the MCP
browser/crawler conditionalization work; remove the doc from this PR or split it
into its own PR: either revert the modifications to the Agent/Team Relationship
Matrix (the regenerated content under the "Agent/Team Relationship Matrix"
heading and all table/matrix changes) so only MCP-related changes remain, or
create a separate branch/PR for the rebranding/matrix regeneration (if
intentional) and exclude any run artifacts from tools like agentkit:sync that
produced these diffs before merging the MCP changes.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/instructions/languages/template-protection.md:
- Line 9: The document contains contradictory guidance: one directive mandates
that changes to templates/specs/engines/overlays must go through a PR to the
retort repository, while another permits local edits to `.agentkit/spec/` with a
sync—clarify by making a single rule that the retort repository is the canonical
source and any change intended to be shared or shipped must be submitted via PR,
while allowing a clearly marked exception that developers may edit
`.agentkit/spec/` locally for experimentation or testing only (explicitly
disallowed from being synced/pushed as authoritative without a PR); update the
wording where the "Rules preventing AI agents..." sentence and the "users may
edit `.agentkit/spec/` locally" sentence appear so they consistently state the
PR requirement for authoritative changes and the local-edit exception for
temporary/test use.
- Line 27: Update the stale header text in the tp-no-generated-edit rule:
replace the quoted marker "GENERATED by AgentKit Forge — DO NOT EDIT" with the
actual header used in the repo (the Retort-generated header string used on line
1) so guidance matches current files; specifically edit the rule text that
begins "**[tp-no-generated-edit]**" to reference the Retort header string
exactly and keep the instruction that AI agents must not edit files with that
header, suggesting spec changes in .agentkit/spec/ instead.

In `@AGENT_BACKLOG.md`:
- Around line 1-3: The top-of-file generated notice ("<!-- GENERATED by Retort
v3.1.0 — DO NOT EDIT -->") conflicts with the footer text that invites direct
edits; update AGENT_BACKLOG.md so the messages are consistent: either remove or
soften the "DO NOT EDIT" phrase in the header (or replace it with "Generated by
Retort v3.1.0 — edits to generated sections may be overwritten") or change the
footer wording to remove the invitation to "edit this file directly", and, if
you want mixed editability, explicitly annotate sections as editable vs
auto-generated (e.g., add clear markers for generated blocks and a short note
describing which sections are safe to modify). Ensure you reference and change
the exact header comment string and the footer lines that mention direct editing
to avoid future confusion.
- Around line 1-157: The AGENT_BACKLOG.md change appears to be an incidental
Retort-generated documentation regen unrelated to the PR goal ("make
browser/crawler MCP servers conditional on project.yaml"); either remove
AGENT_BACKLOG.md from this PR (unstage/revert the changes to that file) or
explicitly document the regeneration in the PR description and split the
backlog/doc refresh into a separate documentation-update PR; mention "Retort"
regeneration and the shifted commands (/orchestrate vs /sync-backlog, agentkit
import-issues) so reviewers understand it is intentional if you keep it.
- Around line 103-105: Update the task lifecycle line in AGENT_BACKLOG.md to
list the full set of implemented states from
.agentkit/templates/claude/commands/orchestrate.md: submitted → accepted →
working → completed/failed/rejected/canceled (and include the special blocked
state BLOCKED_ON_CANCELED used when all blockers are canceled or failed); also
explicitly classify initial (submitted), transient (accepted, working), and
terminal (completed, failed, rejected, canceled, BLOCKED_ON_CANCELED) states so
the documentation matches the actual state machine.

In `@docs/engineering/04_git_workflow.md`:
- Around line 13-17: The branch strategy table is inconsistent: the second row
incorrectly lists `main` as the integration/staging branch; update that row to
the correct integration branch (e.g., change the branch name from `main` to
`dev`) so the table reads `main` = Production-ready code → Production and `dev`
= Integration branch → Staging, leaving `feature/*` as-is.
- Around line 1-3: The generated file header indicates this doc was edited
in-place; revert any direct edits to docs/engineering/04_git_workflow.md and
instead update the source spec under .agentkit/spec (or relevant overlay), then
regenerate the output by running the sync command (pnpm --dir .agentkit
agentkit:sync or pnpm --dir .agentkit retort:sync as appropriate) and commit the
regenerated docs; ensure the file header remains the autogenerated comment
("GENERATED by ... — DO NOT EDIT") to prevent future direct edits.
- Around line 80-84: Update the status check list entries under the branch
protection section to match the exact branch-protection names: replace `Test`
with `Retort CI / Test (ubuntu-latest)`, replace `Validate` with `Retort CI /
Validate`, add the missing `YAML Lint` entry, and keep `Branch Protection /
branch-rules` as-is so the documented checks exactly match the configured branch
protection rules.

---

Outside diff comments:
In `@docs/agents/agent-team-matrix.md`:
- Around line 1-340: This change regenerates the "Agent/Team Relationship
Matrix" documentation (rebranding to "Retort" and wide matrix/table diffs) which
is unrelated to the MCP browser/crawler conditionalization work; remove the doc
from this PR or split it into its own PR: either revert the modifications to the
Agent/Team Relationship Matrix (the regenerated content under the "Agent/Team
Relationship Matrix" heading and all table/matrix changes) so only MCP-related
changes remain, or create a separate branch/PR for the rebranding/matrix
regeneration (if intentional) and exclude any run artifacts from tools like
agentkit:sync that produced these diffs before merging the MCP changes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e1b48a68-4b85-442d-83b0-1437d81839b9

📥 Commits

Reviewing files that changed from the base of the PR and between 1d1f614 and d7bbe4a.

📒 Files selected for processing (84)

• .agentkit/engines/node/src/synchronize.mjs
• .agentkit/engines/node/src/var-builders.mjs
• .agentkit/templates/mcp/servers.json
• .agents/skills/test/SKILL.md
• .claude/skills/test/SKILL.md
• .editorconfig
• .github/CODEOWNERS
• .github/ISSUE_TEMPLATE/bug_report.yml
• .github/ISSUE_TEMPLATE/config.yml
• .github/ISSUE_TEMPLATE/feature_request.yml
• .github/PULL_REQUEST_TEMPLATE.md
• .github/instructions/README.md
• .github/instructions/code-verify.md
• .github/instructions/docs.md
• .github/instructions/languages/README.md
• .github/instructions/languages/agent-conduct.md
• .github/instructions/languages/ci-cd.md
• .github/instructions/languages/dependency-management.md
• .github/instructions/languages/documentation.md
• .github/instructions/languages/git-workflow.md
• .github/instructions/languages/security.md
• .github/instructions/languages/template-protection.md
• .github/instructions/languages/testing.md
• .github/instructions/languages/typescript.md
• .github/instructions/marketing.md
• .github/instructions/performance.md
• .github/instructions/quality.md
• .github/instructions/testing.md
• .prettierrc
• .vscode/settings.json
• AGENT_BACKLOG.md
• CHANGELOG.md
• CONTRIBUTING.md
• MIGRATIONS.md
• SECURITY.md
• docs/agents/agent-team-matrix.md
• docs/api/01_overview.md
• docs/api/02_endpoints.md
• docs/api/03_authentication.md
• docs/api/04_examples.md
• docs/api/05_errors.md
• docs/api/06_versioning.md
• docs/architecture/01_overview.md
• docs/architecture/decisions/01-adopt-agentkit-forge.md
• docs/architecture/decisions/02-fallback-policy-tokens-problem.md
• docs/architecture/decisions/03-tooling-strategy.md
• docs/architecture/decisions/04-static-security-analysis-depth-tooling.md
• docs/architecture/decisions/05-dependency-supply-chain-detection-tooling.md
• docs/architecture/decisions/06-code-quality-maintainability-signal-tooling.md
• docs/architecture/diagrams/.gitkeep
• docs/architecture/specs/01_functional_spec.md
• docs/architecture/specs/02_technical_spec.md
• docs/architecture/specs/03_api_spec.md
• docs/architecture/specs/04_data_models.md
• docs/engineering/01_setup.md
• docs/engineering/02_coding_standards.md
• docs/engineering/03_testing.md
• docs/engineering/04_git_workflow.md
• docs/engineering/05_security.md
• docs/engineering/06_pr_documentation.md
• docs/engineering/07_changelog.md
• docs/history/bug-fixes/TEMPLATE-bugfix.md
• docs/history/features/TEMPLATE-feature.md
• docs/history/implementations/TEMPLATE-implementation.md
• docs/history/issues/TEMPLATE-issue.md
• docs/history/lessons-learned/TEMPLATE-lesson.md
• docs/history/migrations/TEMPLATE-migration.md
• docs/integrations/01_external_apis.md
• docs/integrations/02_webhooks.md
• docs/integrations/03_sdk.md
• docs/operations/01_deployment.md
• docs/operations/02_monitoring.md
• docs/operations/03_incident_response.md
• docs/operations/04_troubleshooting.md
• docs/operations/05_slos_slis.md
• docs/planning/TEMPLATE-plan.md
• docs/product/01_prd.md
• docs/product/02_user_stories.md
• docs/product/03_roadmap.md
• docs/product/04_personas.md
• docs/reference/01_glossary.md
• docs/reference/02_faq.md
• docs/reference/03_changelog.md
• docs/reference/04_contributing.md

✅ Files skipped from review due to trivial changes (75)

• docs/engineering/03_testing.md
• SECURITY.md
• docs/history/features/TEMPLATE-feature.md
• docs/engineering/05_security.md
• docs/api/01_overview.md
• docs/engineering/07_changelog.md
• docs/architecture/specs/02_technical_spec.md
• docs/integrations/01_external_apis.md
• docs/engineering/01_setup.md
• docs/history/lessons-learned/TEMPLATE-lesson.md
• docs/architecture/specs/04_data_models.md
• .github/ISSUE_TEMPLATE/feature_request.yml
• .github/ISSUE_TEMPLATE/bug_report.yml
• docs/api/05_errors.md
• docs/api/03_authentication.md
• docs/engineering/06_pr_documentation.md
• docs/product/03_roadmap.md
• docs/history/implementations/TEMPLATE-implementation.md
• .github/ISSUE_TEMPLATE/config.yml
• docs/product/02_user_stories.md
• docs/engineering/02_coding_standards.md
• docs/architecture/decisions/04-static-security-analysis-depth-tooling.md
• docs/operations/01_deployment.md
• .github/instructions/docs.md
• docs/operations/03_incident_response.md
• docs/product/04_personas.md
• docs/reference/03_changelog.md
• docs/operations/05_slos_slis.md
• .github/instructions/marketing.md
• docs/reference/02_faq.md
• docs/history/bug-fixes/TEMPLATE-bugfix.md
• docs/history/migrations/TEMPLATE-migration.md
• docs/product/01_prd.md
• docs/api/06_versioning.md
• docs/api/04_examples.md
• CHANGELOG.md
• docs/reference/01_glossary.md
• docs/planning/TEMPLATE-plan.md
• .github/PULL_REQUEST_TEMPLATE.md
• docs/reference/04_contributing.md
• .agents/skills/test/SKILL.md
• docs/architecture/specs/03_api_spec.md
• docs/architecture/decisions/05-dependency-supply-chain-detection-tooling.md
• docs/integrations/03_sdk.md
• docs/operations/04_troubleshooting.md
• .vscode/settings.json
• .github/CODEOWNERS
• docs/architecture/diagrams/.gitkeep
• .github/instructions/languages/dependency-management.md
• docs/architecture/decisions/06-code-quality-maintainability-signal-tooling.md
• docs/api/02_endpoints.md
• docs/architecture/decisions/03-tooling-strategy.md
• docs/integrations/02_webhooks.md
• .github/instructions/README.md
• docs/history/issues/TEMPLATE-issue.md
• .github/instructions/testing.md
• docs/architecture/01_overview.md
• docs/architecture/decisions/02-fallback-policy-tokens-problem.md
• .github/instructions/performance.md
• docs/architecture/specs/01_functional_spec.md
• .github/instructions/languages/documentation.md
• .github/instructions/code-verify.md
• .editorconfig
• .prettierrc
• .agentkit/engines/node/src/synchronize.mjs
• MIGRATIONS.md
• .github/instructions/languages/typescript.md
• docs/operations/02_monitoring.md
• .github/instructions/languages/README.md
• .github/instructions/languages/agent-conduct.md
• .github/instructions/quality.md
• CONTRIBUTING.md
• docs/architecture/decisions/01-adopt-agentkit-forge.md
• .claude/skills/test/SKILL.md
• .github/instructions/languages/testing.md

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Clarify spec-edit policy to avoid contradictory instructions.

Line 9 says spec changes must go through a PR to the retort repository, but Line 25 says users may edit .agentkit/spec/ locally and run sync. These two directives conflict and can block expected workflows.

Proposed wording adjustment

-Rules preventing AI agents from directly modifying Retort source-of-truth files. Changes to templates, specs, engines, and overlays must go through a PR to the retort repository.
+Rules preventing AI agents from directly modifying Retort source-of-truth files. Changes to templates, engines, and overlays must go through a PR to the retort repository. Project users may update `.agentkit/spec/` locally and regenerate outputs.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	Rules preventing AI agents from directly modifying Retort source-of-truth files. Changes to templates, specs, engines, and overlays must go through a PR to the retort repository.
	Rules preventing AI agents from directly modifying Retort source-of-truth files. Changes to templates, engines, and overlays must go through a PR to the retort repository. Project users may update `.agentkit/spec/` locally and regenerate outputs.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/instructions/languages/template-protection.md at line 9, The
document contains contradictory guidance: one directive mandates that changes to
templates/specs/engines/overlays must go through a PR to the retort repository,
while another permits local edits to `.agentkit/spec/` with a sync—clarify by
making a single rule that the retort repository is the canonical source and any
change intended to be shared or shipped must be submitted via PR, while allowing
a clearly marked exception that developers may edit `.agentkit/spec/` locally
for experimentation or testing only (explicitly disallowed from being
synced/pushed as authoritative without a PR); update the wording where the
"Rules preventing AI agents..." sentence and the "users may edit
`.agentkit/spec/` locally" sentence appear so they consistently state the PR
requirement for authoritative changes and the local-edit exception for
temporary/test use.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Update stale generated-header marker text.

Line 27 still references "GENERATED by AgentKit Forge — DO NOT EDIT" while Line 1 now uses Retort. This should be aligned so guidance matches actual headers.

Proposed wording fix

-- **[tp-no-generated-edit]** AI agents must never directly edit files marked with the header "GENERATED by AgentKit Forge — DO NOT EDIT". Instead, suggest the relevant YAML spec change in .agentkit/spec/ to a human reviewer; only users (not AI agents) may modify spec YAML files and run agentkit sync to regenerate output.
+- **[tp-no-generated-edit]** AI agents must never directly edit files marked with the header "GENERATED by Retort v3.1.0 — DO NOT EDIT". Instead, suggest the relevant YAML spec change in .agentkit/spec/ to a human reviewer; only users (not AI agents) may modify spec YAML files and run agentkit sync to regenerate output.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/instructions/languages/template-protection.md at line 27, Update the
stale header text in the tp-no-generated-edit rule: replace the quoted marker
"GENERATED by AgentKit Forge — DO NOT EDIT" with the actual header used in the
repo (the Retort-generated header string used on line 1) so guidance matches
current files; specifically edit the rule text that begins
"**[tp-no-generated-edit]**" to reference the Retort header string exactly and
keep the instruction that AI agents must not edit files with that header,
suggesting spec changes in .agentkit/spec/ instead.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

"DO NOT EDIT" header conflicts with manual editing guidance in footer.

Lines 1-3 state "GENERATED by Retort v3.1.0 — DO NOT EDIT", but lines 156-157 explicitly encourage "edit this file directly for manual adjustments." This creates confusion about whether manual edits are permitted or will be overwritten on next sync.

Consider either:

• Removing the "DO NOT EDIT" warning if manual edits are intended to be preserved
• Changing the footer to only mention /orchestrate without suggesting direct edits
• Clarifying which sections are editable vs. auto-generated

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@AGENT_BACKLOG.md` around lines 1 - 3, The top-of-file generated notice ("<!--
GENERATED by Retort v3.1.0 — DO NOT EDIT -->") conflicts with the footer text
that invites direct edits; update AGENT_BACKLOG.md so the messages are
consistent: either remove or soften the "DO NOT EDIT" phrase in the header (or
replace it with "Generated by Retort v3.1.0 — edits to generated sections may be
overwritten") or change the footer wording to remove the invitation to "edit
this file directly", and, if you want mixed editability, explicitly annotate
sections as editable vs auto-generated (e.g., add clear markers for generated
blocks and a short note describing which sections are safe to modify). Ensure
you reference and change the exact header comment string and the footer lines
that mention direct editing to avoid future confusion.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Verify this file's inclusion in an MCP-focused PR.

This entire file is a backlog management document that doesn't relate to the PR's stated objective: "make browser/crawler MCP servers conditional on project.yaml". The AI summary confirms this is a regeneration that replaces "agentkit-forge" style with "Retort" style and shifts workflows from /sync-backlog/agentkit import-issues to /orchestrate.

This appears to be an incidental regeneration rather than a purposeful change for MCP server configuration. If this regeneration is intentional and part of a broader documentation refresh, that should be noted in the PR description. Otherwise, consider whether this file should be included in this PR or moved to a separate documentation-update PR.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@AGENT_BACKLOG.md` around lines 1 - 157, The AGENT_BACKLOG.md change appears
to be an incidental Retort-generated documentation regen unrelated to the PR
goal ("make browser/crawler MCP servers conditional on project.yaml"); either
remove AGENT_BACKLOG.md from this PR (unstage/revert the changes to that file)
or explicitly document the regeneration in the PR description and split the
backlog/doc refresh into a separate documentation-update PR; mention "Retort"
regeneration and the shifted commands (/orchestrate vs /sync-backlog, agentkit
import-issues) so reviewers understand it is intentional if you keep it.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Verify task JSON files mechanism and dashboard integration

echo "=== Checking task JSON implementation ==="

# Check if .claude/state/tasks directory exists or is referenced in code
echo -e "\n1. Task directory references:"
fd -t d 'tasks' .claude/state 2>/dev/null || echo "Directory not found"
rg -n '\.claude/state/tasks' --type=ts --type=js --type=mjs

# Check for dashboard implementation
echo -e "\n2. Project status dashboard references:"
rg -n -C3 'project-status|dashboard.*throughput|WIP count|lead time' --type=ts --type=js --type=mjs --type=md

# Check orchestrate command for task file creation logic
echo -e "\n3. Task file creation in orchestrate:"
rg -n -C3 'submitted|accepted|working|completed.*task.*json|task.*lifecycle' .agentkit/templates/claude/commands/orchestrate.md

Repository: phoenixvc/retort

Length of output: 2428

---

🏁 Script executed:

# Search for dashboard, metrics, or task tracking implementations
echo "=== Broader dashboard/metrics search ==="

# Look for any dashboard or reporting implementation
rg -n 'dashboard|metrics|throughput|lead.*time' -i --type=ts --type=js

# Search for task file creation/reading beyond templates
rg -n 'tasks.*json|\.claude/state' -i

# Check if AGENT_BACKLOG.md itself clarifies planned vs. implemented
grep -n "planned\|TODO\|[Pp]roposed\|not.*implement" AGENT_BACKLOG.md | head -20

# Look for any state directory creation
rg -n '\.claude.*state' --type=ts --type=js

# Check directory structure
echo -e "\n=== Directory structure under .claude ==="
find .claude -type f 2>/dev/null | head -20

Repository: phoenixvc/retort

Length of output: 19352

---

🏁 Script executed:

# Check TasksPanel component for metric calculations
echo "=== TasksPanel metrics ==="
cat -n src/start/components/TasksPanel.tsx | head -50

# Check dashboard command implementation
echo -e "\n=== Dashboard command implementation ==="
rg -n -A15 "desc.*dashboard|progress.*risks" src/start/lib/commands.ts

# Check for WIP, throughput, lead time calculations
echo -e "\n=== Specific metrics calculation ==="
rg -n 'WIP|throughput|lead.*time|active.*count' -i src/start/ --type=ts --type=tsx --type=js

Repository: phoenixvc/retort

Length of output: 2305

---

🏁 Script executed:

# Find the dashboard command implementation/handler
echo "=== Dashboard handler implementation ==="
rg -n -A20 "dashboard|project-status" src/start/lib/commands.ts | grep -A20 "handler\|fn\|exec"

# Look for separate dashboard implementation
echo -e "\n=== Dashboard related files ==="
fd -t f 'dashboard|metrics' src/

# Check if dashboard is defined in a separate file or if it's a reference
echo -e "\n=== Search for /dashboard or project-dashboard command handler ==="
rg -n 'handler.*dashboard|/dashboard.*handler|\bdashboard\b.*=' src/start --type=ts --type=js -A5

# Look at the actual command implementation to see how metrics are exposed
echo -e "\n=== Commands file full context around dashboard ==="
sed -n '85,110p' src/start/lib/commands.ts

Repository: phoenixvc/retort

Length of output: 1020

---

🏁 Script executed:

# Search for /project-status handler in agentkit templates
echo "=== Search for /project-status handler ==="
find .agentkit -type f -name "*.md" -o -name "*.sh" | xargs grep -l "project-status" 2>/dev/null

# Check if it's a template command
echo -e "\n=== Check template commands ==="
ls -la .agentkit/templates/claude/commands/ | grep -i project

# Look for where commands are executed/handled
echo -e "\n=== Search for command execution/routing ==="
rg -n "project-status|/project-status" --type=md --type=mjs --type=js --type=ts -B2 -A5

# Check README or documentation for dashboard behavior
echo -e "\n=== Check dashboard metrics documentation ==="
rg -n "throughput|WIP count|lead time" --type=md -B2 -A2

Repository: phoenixvc/retort

Length of output: 13927

---

🏁 Script executed:

# Check the project-status.md template to see what metrics it actually displays
echo "=== Project-status template implementation ==="
head -100 .agentkit/templates/claude/commands/project-status.md

echo -e "\n=== Check for metric calculation or N/A handling ==="
rg -n "N/A|unavailable|not.*implement|TODO|planned" .agentkit/templates/claude/commands/project-status.md

Repository: phoenixvc/retort

Length of output: 4078

---

Update task lifecycle documentation to include all implemented states.

The task JSON files mechanism and project-status dashboard are correctly implemented. However, the documented lifecycle is incomplete. The actual lifecycle includes eight states:

Current (incomplete) in AGENT_BACKLOG.md: submitted → accepted → working → completed/failed/rejected

Should be: submitted → accepted → working → completed/failed/rejected/canceled (with blocked state: BLOCKED_ON_CANCELED when all blockers are canceled or failed)

Update lines 103-105 to reflect the full state machine from .agentkit/templates/claude/commands/orchestrate.md, which documents valid transitions and distinguishes between initial (submitted), transient (accepted, working), and terminal (completed, failed, rejected, canceled, BLOCKED_ON_CANCELED) states.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@AGENT_BACKLOG.md` around lines 103 - 105, Update the task lifecycle line in
AGENT_BACKLOG.md to list the full set of implemented states from
.agentkit/templates/claude/commands/orchestrate.md: submitted → accepted →
working → completed/failed/rejected/canceled (and include the special blocked
state BLOCKED_ON_CANCELED used when all blockers are canceled or failed); also
explicitly classify initial (submitted), transient (accepted, working), and
terminal (completed, failed, rejected, canceled, BLOCKED_ON_CANCELED) states so
the documentation matches the actual state machine.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Do not edit this generated doc directly; regenerate from source spec instead.

This file is explicitly marked generated, but it was edited in-place. Please apply changes in .agentkit/spec (or overlays) and commit the regenerated output.

As per coding guidelines, "Files with the header 'GENERATED by AgentKit Forge — DO NOT EDIT' must not be edited directly. Modify the source spec in .agentkit/spec/ and run 'pnpm --dir .agentkit agentkit:sync' to regenerate."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/engineering/04_git_workflow.md` around lines 1 - 3, The generated file
header indicates this doc was edited in-place; revert any direct edits to
docs/engineering/04_git_workflow.md and instead update the source spec under
.agentkit/spec (or relevant overlay), then regenerate the output by running the
sync command (pnpm --dir .agentkit agentkit:sync or pnpm --dir .agentkit
retort:sync as appropriate) and commit the regenerated docs; ensure the file
header remains the autogenerated comment ("GENERATED by ... — DO NOT EDIT") to
prevent future direct edits.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Branch strategy table is internally inconsistent.

Line 16 duplicates main as the integration/staging branch, which conflicts with Line 15 (main as production-ready). This likely should be dev (or whichever actual integration branch is used).

Proposed doc fix

-| `main`      | Integration branch    | Staging    |
+| `dev`       | Integration branch    | Staging    |

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	| Branch | Purpose | Deploys To |
	| ----------- | --------------------- | ---------- |
	| `main` | Production-ready code | Production |
	| `develop` | Integration branch | Staging |
	| `main` | Integration branch | Staging |
	| `feature/*` | New features | — |
	| Branch | Purpose | Deploys To |
	| ----------- | --------------------- | ---------- |
	| `main` | Production-ready code | Production |
	| `dev` | Integration branch | Staging |
	| `feature/*` | New features | — |

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/engineering/04_git_workflow.md` around lines 13 - 17, The branch
strategy table is inconsistent: the second row incorrectly lists `main` as the
integration/staging branch; update that row to the correct integration branch
(e.g., change the branch name from `main` to `dev`) so the table reads `main` =
Production-ready code → Production and `dev` = Integration branch → Staging,
leaving `feature/*` as-is.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# First, let's read the full context around lines 80-84 in the documentation file
cat -n docs/engineering/04_git_workflow.md | head -100

Repository: phoenixvc/retort

Length of output: 2997

---

🏁 Script executed:

# Find .agentkit/spec files that might contain git workflow configuration
find .agentkit/spec -type f -name "*.md" -o -name "*.yml" -o -name "*.yaml" -o -name "*.json" | head -20

Repository: phoenixvc/retort

Length of output: 754

---

🏁 Script executed:

# Check the docs.yaml file for git workflow specification
cat -n .agentkit/spec/docs.yaml | grep -A 50 -B 5 "git_workflow\|Branch Protection\|Test\|Validate"

Repository: phoenixvc/retort

Length of output: 3098

---

🏁 Script executed:

# Find GitHub Actions workflow files to see actual check names
find .github/workflows -type f -name "*.yml" -o -name "*.yaml" 2>/dev/null | head -20

Repository: phoenixvc/retort

Length of output: 766

---

🏁 Script executed:

# Read the CI workflow to see what check names are actually produced
cat -n .github/workflows/ci.yml | head -80

Repository: phoenixvc/retort

Length of output: 3180

---

🏁 Script executed:

# Read the branch-protection.yml workflow to see the "branch-rules" check
cat -n .github/workflows/branch-protection.yml

Repository: phoenixvc/retort

Length of output: 6829

---

🏁 Script executed:

# Check the quality-lint.yml workflow to see if it contains the YAML Lint check
cat -n .github/workflows/quality-lint.yml | grep -A 5 "name:\|yaml-lint" | head -40

Repository: phoenixvc/retort

Length of output: 1241

---

🏁 Script executed:

# Search for YAML Lint or yaml-lint in all workflow files
grep -r "yaml" .github/workflows/ --include="*.yml" --include="*.yaml" -i | grep -i "name:\|yaml.*lint"

Repository: phoenixvc/retort

Length of output: 934

---

🏁 Script executed:

# Read the rest of the ci.yml file to see the YAML Lint job and understand all required checks
cat -n .github/workflows/ci.yml | sed -n '80,140p'

Repository: phoenixvc/retort

Length of output: 2726

---

🏁 Script executed:

# Get the definitive status check names from the authoritative workflow comments
grep -A 10 "Configure GitHub branch protection" .github/workflows/branch-protection.yml

Repository: phoenixvc/retort

Length of output: 395

---

Update required status check names to match configured branch protection rules exactly.

The documentation lists simplified check names that don't match the authoritative configuration. Branch protection should require:

• Retort CI / Test (ubuntu-latest)
• Retort CI / Validate
• YAML Lint
• Branch Protection / branch-rules

Update lines 80-84 to include the workflow name prefix and add the missing YAML Lint check.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/engineering/04_git_workflow.md` around lines 80 - 84, Update the status
check list entries under the branch protection section to match the exact
branch-protection names: replace `Test` with `Retort CI / Test (ubuntu-latest)`,
replace `Validate` with `Retort CI / Validate`, add the missing `YAML Lint`
entry, and keep `Branch Protection / branch-rules` as-is so the documented
checks exactly match the configured branch protection rules.