chore(ai-harness): introduce .ai/ agent harness pilot#114
Merged
Conversation
Stand up a team-shared AI agent harness in this repo as the pilot for a broader internal initiative. The harness is committed, multi-agent, and reproducible from a fresh clone. What lands: - `AGENTS.md` becomes the canonical prose-rules file; `CLAUDE.md` is a one-line `@AGENTS.md` shim. Codex, Cursor, Windsurf, VS Code Copilot read AGENTS.md natively; Claude Code via the shim. - `.ai/` directory holds: `LANGUAGE.md` (vocabulary), `plans/` (committed historical plans, migrated from `docs/plans/`), `research/` (date-prefixed artifacts), `memory/` (team product knowledge — product / architecture / stack / lessons / topics / integrations / initiatives), and `skills/` (vendored superpowers v5.0.7, MIT, Jesse Vincent). - `.claude/settings.json` disables the global `superpowers` plugin per project so the vendored copy is the single source of truth. - Symlinks `.claude/skills`, `.agents/skills`, `.cursor/skills` all point to `../.ai/skills`, giving Claude Code, Codex (`.agents/skills/` is the Codex spec path), and Cursor 2.4+ the same skill set without duplication. - `.codex/config.toml` is committed with the project's nx-mcp setup. - Per-package vocabulary cleanup: `apps/cli/AGENTS.md`, `apps/server/AGENTS.md`, and `docs/specs/SPEC-013-mintlify-docs-site.md` updated to drop "device flow" (the CLI uses an OAuth2 loopback redirect, RFC 8252) and to remove references to a non-existent `migrate` CLI command. - `apps/server/AGENTS.md` corrected to reflect that sessions live in Postgres, not Redis (Redis is provisioned for caching/queues but not currently a session store). - `.gitignore` adds `.vercel/`, `*.tsbuildinfo`, the personal local-only paths under `.ai/skills/`, and `.claude/settings.local.json`. - `.prettierignore` excludes vendored `.ai/skills/` and historical `.ai/plans/` so bumps and migrated content stay verbatim. Memory bank shape borrows from Cline's pattern but drops the solo-developer-state files (`active-context.md`, `progress.md`) that cause merge conflicts on concurrent PRs. Stable knowledge lives in single-purpose files; volatile state stays in Jira / `ROADMAP_TASKS.md` / GitHub Issues. Out of scope for this pilot: the generic multi-project installer skill (`/install-dot-ai`-style), an evals suite, hooks for deterministic rule enforcement, an org-level cross-project memory layer. Those are the Phase 2 wishlist if and when the harness proves itself in MDCMS.
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a canonical AI agent framework and skills bundle under Changes
Sequence Diagram(s)sequenceDiagram
participant Agent as Agent (CLI / Operator)
participant Server as Brainstorm Server
participant Browser as Browser Client
participant FS as Filesystem (session/state)
Agent->>Server: start-server.sh creates session dir and starts server
Server-->>Agent: emit "server-started" with URL
Agent->>Browser: open served URL
Browser->>Server: GET page
Server->>FS: read latest .html screen
Server->>Browser: serve HTML (inject helper.js)
Browser->>Server: WebSocket handshake -> connect
Agent->>FS: write new .html screen
FS->>Server: watcher -> file change event
Server->>Browser: broadcast {type:"reload"}
Browser->>Browser: helper.js triggers reload and user interactions
Browser->>Server: WS send {type:'click', choice, text}
Server->>FS: append JSONL event to events file
Agent->>FS: read events to process choices
Agent->>Server: stop-server.sh requests shutdown
Server->>Server: close sockets, write server-stopped marker
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~45 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
…docs Follow-up to the harness pilot, addressing issues caught in review: - `schema sync` (with space) is the actual CLI command name, not `schema-sync` (hyphen). Fixed in `apps/cli/AGENTS.md` and `.ai/memory/topics/push-pull-sync.md`. - Removed `TanStack Router` from `.ai/memory/stack.md` — it's not in any package.json. Fabricated. - Removed stale `Jira` mention from `.ai/memory/README.md`'s integrations index; the file was deliberately not committed (refers to user-local Jira/MCP setup). - Dropped pre-push-hook claims in `AGENTS.md`, `.ai/memory/stack.md`, and `.ai/memory/integrations/github-actions.md` — no such hook is configured. Reframed as a manual local step. - Tightened `.ai/memory/topics/multi-tenancy.md` "Storage layer" bullets to match the softened "tenant-scoped" framing already in the file's intro paragraph (auth tables don't carry `project_id`).
The first commit on this branch backfilled 76 plan files from the local-only `docs/plans/` working directory into `.ai/plans/`. On review that's mostly redundant with `docs/specs/`, `docs/adrs/`, and the merged PR history — execution plans for already-shipped CMS-NN tickets don't add durable team knowledge that the canonical docs don't already capture. Drop the 76 historical plans from the PR. The directory survives via `.gitkeep` so the convention is in place, and new plans created by the `writing-plans` skill going forward will be tracked normally. Local copies of the historical plans remain untouched in the working tree — anyone who wants to fold a specific plan's reasoning into an ADR or `.ai/research/` artifact can still do so. Updates AGENTS.md's `.ai/plans/` description from "historical record" to "populated as new work happens" to reflect the new framing.
The Nx-MCP setup was Karol's local Codex configuration, not something
the team uses uniformly. Per the principle that committed files must
make sense for any contributor cloning the repo, removing:
- `.ai/memory/integrations/nx-mcp.md`
- `.codex/config.toml` (and the empty `.codex/` directory it left behind)
- References to Nx-MCP in `AGENTS.md` and `.ai/memory/{README,integrations/README}.md`
Codex CLI users can configure their own MCP servers via `~/.codex/`
without per-project config in this repo.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
🟡 Minor comments (26)
.prettierignore-11-12 (1)
11-12:⚠️ Potential issue | 🟡 MinorUpdate stale comment for
.ai/plans/intent.The ignore entry looks fine, but the comment references migrated historical plans, while this PR removed backfilled historical plans. Please reword to reflect current usage (ongoing/generated plans).
Suggested wording
-# Migrated historical plans — preserve original formatting +# Agent-generated plans — preserve formatting to reduce churn /.ai/plans/🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.prettierignore around lines 11 - 12, Update the stale comment above the /.ai/plans/ ignore entry in .prettierignore to reflect current intent (ongoing/generated plans) instead of "migrated historical plans"; locate the comment text immediately preceding the "/.ai/plans/" entry and replace the wording so it clearly indicates the directory holds active/auto-generated plan files (for example: "Ongoing/generated plan files — preserve original formatting") while keeping the ignore entry unchanged..ai/skills/brainstorming/scripts/frame-template.html-3-5 (1)
3-5:⚠️ Potential issue | 🟡 MinorAdd a viewport meta tag for mobile correctness.
Without a viewport declaration, responsive rules can render scaled/zoomed on small screens.
Suggested change
<head> <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Superpowers Brainstorming</title>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.ai/skills/brainstorming/scripts/frame-template.html around lines 3 - 5, The HTML head is missing a viewport meta tag causing incorrect scaling on mobile; inside the <head> (near the existing <meta charset="utf-8"> and <title>Superpowers Brainstorming</title>) add a responsive viewport meta tag (e.g., name="viewport" content="width=device-width, initial-scale=1") so the page uses device width and proper initial-scale for mobile rendering..ai/skills/writing-skills/render-graphs.js-29-33 (1)
29-33:⚠️ Potential issue | 🟡 MinorDuplicate graph names can silently overwrite SVG outputs.
If two
dotblocks share the samedigraphname, later writes replace earlier files.💡 Proposed fix
- for (const block of blocks) { + const usedNames = new Map(); + for (const block of blocks) { const svg = renderToSvg(block.content); if (svg) { - const outputPath = path.join(outputDir, `${block.name}.svg`); + const seen = usedNames.get(block.name) ?? 0; + usedNames.set(block.name, seen + 1); + const fileName = seen === 0 ? block.name : `${block.name}_${seen + 1}`; + const outputPath = path.join(outputDir, `${fileName}.svg`); fs.writeFileSync(outputPath, svg); - console.log(` Rendered: ${block.name}.svg`); + console.log(` Rendered: ${fileName}.svg`); } else { console.error(` Failed: ${block.name}`); } }Also applies to: 156-157
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.ai/skills/writing-skills/render-graphs.js around lines 29 - 33, Multiple dot blocks can end up with identical 'name' values (derived from nameMatch) causing later SVG writes to overwrite earlier ones; update the logic around the name derivation (the nameMatch/name variables and where blocks.push({ name, content }) is called) to guarantee unique filenames by detecting existing names in the blocks array and appending a disambiguating suffix or index (e.g., name + '_1', '_2' or a short unique id) before pushing, and apply the same uniqueness logic to the other occurrence referenced around the code at the lines corresponding to the second instance (the same name/nameMatch usage near lines 156-157)..ai/skills/using-git-worktrees/SKILL.md-42-49 (1)
42-49:⚠️ Potential issue | 🟡 MinorAdd fence languages for markdownlint MD040 compliance.
The unlabeled fenced blocks at Line 42, Line 138, and Line 180 trigger the reported warning.
💡 Proposed fix
-``` +```text No worktree directory found. Where should I create worktrees? ... Which would you prefer?-
+text
Worktree ready at
...
Ready to implement-``` +```text You: I'm using the using-git-worktrees skill to set up an isolated workspace. ... Ready to implement auth feature</details> Also applies to: 138-142, 180-192 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/using-git-worktrees/SKILL.md around lines 42 - 49, The Markdown
file .ai/skills/using-git-worktrees/SKILL.md contains unlabeled fenced code
blocks (e.g., the block starting "No worktree directory found. Where should I
create worktrees?", the block containing "Worktree ready at ", and
the block beginning "You: I'm using the using-git-worktrees skill...") which
trigger markdownlint MD040; fix by adding a fence language (use "text") to each
triple-backtick fence that wraps those blocks so they becometext ...and
ensure all three occurrences are updated consistently.</details> </blockquote></details> <details> <summary>.ai/skills/systematic-debugging/condition-based-waiting-example.ts-29-39 (1)</summary><blockquote> `29-39`: _⚠️ Potential issue_ | _🟡 Minor_ **Add defensive error handling in polling callbacks to prevent unhandled rejections.** Errors thrown in `setTimeout` callbacks are not caught by the Promise executor. While `threadManager.getEvents()` may not throw under normal conditions, defensive error handling would prevent test hangs if an unexpected error occurs during polling. <details> <summary>Proposed fix</summary> ```diff const check = () => { + try { const events = threadManager.getEvents(threadId); const event = events.find((e) => e.type === eventType); if (event) { resolve(event); } else if (Date.now() - startTime > timeoutMs) { reject(new Error(`Timeout waiting for ${eventType} event after ${timeoutMs}ms`)); } else { setTimeout(check, 10); } + } catch (error) { + reject(error instanceof Error ? error : new Error(String(error))); + } }; ``` </details> Also applies to: 70-85, 121-131 <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/systematic-debugging/condition-based-waiting-example.ts around lines 29 - 39, The polling callback function check should be made defensive: wrap its body in a try/catch and call reject(err) inside the catch to avoid unhandled exceptions from setTimeout; also guard resolution by tracking a local "settled" boolean so you don't call resolve/reject twice (update places referencing threadManager.getEvents, resolve, reject, and setTimeout(check, 10)). Apply the same pattern to the other polling blocks (the ones around lines 70-85 and 121-131) so any unexpected errors during threadManager.getEvents or event processing are caught and cause the Promise to reject instead of throwing in the timer. ``` </details> </blockquote></details> <details> <summary>.ai/skills/systematic-debugging/test-pressure-1.md-5-5 (1)</summary><blockquote> `5-5`: _⚠️ Potential issue_ | _🟡 Minor_ **Path reference likely inconsistent with current skill location.** Line 5 uses `skills/debugging/systematic-debugging`; please align this with the canonical skill path used in `.ai/skills/`. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/systematic-debugging/test-pressure-1.md at line 5, The reference string "skills/debugging/systematic-debugging" is inconsistent with the canonical skill path used under .ai/skills; update the string to the correct canonical skill path used in the repository (replace "skills/debugging/systematic-debugging" with the repository's canonical .ai/skills path for the systematic-debugging skill), or look up the existing canonical skill folder name under .ai/skills and align this reference to that exact path so imports/links are consistent. ``` </details> </blockquote></details> <details> <summary>.ai/skills/requesting-code-review/SKILL.md-105-105 (1)</summary><blockquote> `105-105`: _⚠️ Potential issue_ | _🟡 Minor_ **Fix the template link path to avoid a broken relative reference.** From this file’s location, `requesting-code-review/code-reviewer.md` likely resolves incorrectly; use `code-reviewer.md` (same folder) or an absolute repo path. <details> <summary>Suggested fix</summary> ```diff -See template at: requesting-code-review/code-reviewer.md +See template at: code-reviewer.md ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/requesting-code-review/SKILL.md at line 105, The template link in .ai/skills/requesting-code-review/SKILL.md currently points to "requesting-code-review/code-reviewer.md" which creates a broken relative reference; update that link target to the correct local path "code-reviewer.md" (or an absolute repo path like "/.ai/skills/requesting-code-review/code-reviewer.md") so the link resolves from the current file location, ensuring the displayed link text stays the same and only the href/target string is changed. ``` </details> </blockquote></details> <details> <summary>.ai/skills/systematic-debugging/test-pressure-1.md-17-19 (1)</summary><blockquote> `17-19`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language hint for the inline log snippet fence.** The code fence at Line 17 is unlabeled and triggers MD040; `text` is sufficient here. <details> <summary>Suggested fix</summary> ```diff -``` +```text PaymentError: Connection timeout to payments.api.com ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/systematic-debugging/test-pressure-1.md around lines 17 - 19, Add
a language hint "text" to the unlabeled inline code fence containing the log
snippet "PaymentError: Connection timeout to payments.api.com" so the fence
becomes a labeled text block (this fixes MD040); update the fence that wraps
that exact log snippet to start withtext instead of justand keep the
snippet content unchanged.</details> </blockquote></details> <details> <summary>.ai/skills/systematic-debugging/test-pressure-3.md-5-5 (1)</summary><blockquote> `5-5`: _⚠️ Potential issue_ | _🟡 Minor_ **Fix the incorrect skill path reference.** Line 5 contains a non-canonical path reference: `skills/debugging/systematic-debugging` does not match the actual directory structure. The correct skill name is `systematic-debugging` (without the "debugging" subdirectory). Per the project's own documentation in `writing-skills/SKILL.md`, skill references should use only the skill name (e.g., `systematic-debugging` or `superpowers:systematic-debugging`), not full paths like `skills/testing/test-driven-development`. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/systematic-debugging/test-pressure-3.md at line 5, Replace the non-canonical skill path string "skills/debugging/systematic-debugging" with the canonical skill name "systematic-debugging" (or the namespaced form "superpowers:systematic-debugging") in the file where it appears; locate the literal "skills/debugging/systematic-debugging" and update it to "systematic-debugging" to match the project's SKILL.md conventions. ``` </details> </blockquote></details> <details> <summary>.ai/skills/requesting-code-review/SKILL.md-51-75 (1)</summary><blockquote> `51-75`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language tag to the example fence.** The fenced block at Line 51 is unlabeled and triggers MD040; use `text` (or `markdown`) since it’s mixed prose/commands. <details> <summary>Suggested fix</summary> ```diff -``` +```text [Just completed Task 2: Add verification function] @@ -``` +``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/requesting-code-review/SKILL.md around lines 51 - 75, The fenced
code block starting with "[Just completed Task 2: Add verification function]" is
missing a language tag (MD040); update the opening triple backticks in
.ai/skills/requesting-code-review/SKILL.md to use a language label such as
text(ormarkdown) so the fence becomes ```text, keeping the exact block
contents including the commands and summary unchanged; this removes the MD040
lint warning without altering the sample commands or descriptions.</details> </blockquote></details> <details> <summary>.ai/skills/subagent-driven-development/spec-reviewer-prompt.md-7-61 (1)</summary><blockquote> `7-61`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language to the fenced code block for markdownlint compliance.** Line 7 starts an unlabeled fence, which triggers MD040 and can fail docs lint in stricter pipelines. <details> <summary>Suggested fix</summary> ```diff -``` +```yaml Task tool (general-purpose): description: "Review spec compliance for Task N" prompt: | @@ -``` +``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/subagent-driven-development/spec-reviewer-prompt.md around lines
7 - 61, The Markdown fenced code block that begins before the "Task tool
(general-purpose):" block is unlabeled and triggers MD040; update the opening
fence fromto a labeled fence likeyaml so markdownlint accepts it.
Locate the unlabeled fence surrounding the Task tool prompt (the block
containing "Task tool (general-purpose):" and the prompt content) and change
only the opening fence to include the language identifier (yaml) while leaving
the closing fence untouched.</details> </blockquote></details> <details> <summary>.ai/skills/subagent-driven-development/implementer-prompt.md-5-113 (1)</summary><blockquote> `5-113`: _⚠️ Potential issue_ | _🟡 Minor_ **Specify a fence language on the main template block.** Line 5 uses a plain fence; add a language (e.g., `yaml`) to satisfy MD040 and improve readability. <details> <summary>Suggested fix</summary> ```diff -``` +```yaml Task tool (general-purpose): description: "Implement Task N: [task name]" prompt: | @@ -``` +``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/subagent-driven-development/implementer-prompt.md around lines 5
- 113, The top-level code fence enclosing the Task tool template (the block that
begins with "Task tool (general-purpose):" and the prompt content) lacks a
fenced language which triggers MD040; update the opening triple-backtick to
include a language such as yaml (e.g., changetoyaml) so the code block
is explicitly marked, leaving the rest of the template unchanged and keeping the
closing ``` as-is.</details> </blockquote></details> <details> <summary>.ai/skills/systematic-debugging/test-academic.md-3-3 (1)</summary><blockquote> `3-3`: _⚠️ Potential issue_ | _🟡 Minor_ **Update skill path reference to correct location.** Line 3 references `skills/debugging/systematic-debugging`, but this path does not exist. The correct path is `.ai/skills/systematic-debugging` (the canonical location for internal dev-time skills per AGENTS.md). <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/systematic-debugging/test-academic.md at line 3, Update the incorrect skill path string "skills/debugging/systematic-debugging" to the canonical ".ai/skills/systematic-debugging" in the file .ai/skills/systematic-debugging/test-academic.md; locate the line containing the literal text "You have access to the systematic debugging skill at skills/debugging/systematic-debugging" and replace that path, and scan the file for any other occurrences of the old path and update them as well. ``` </details> </blockquote></details> <details> <summary>.ai/skills/requesting-code-review/code-reviewer.md-112-146 (1)</summary><blockquote> `112-146`: _⚠️ Potential issue_ | _🟡 Minor_ **Add language to the example fenced block.** At **Line 112**, the code fence is missing a language identifier and triggers MD040. Add `markdown` (or `text`) for lint consistency. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/requesting-code-review/code-reviewer.md around lines 112 - 146,
The fenced code block that begins at the "### Strengths" section in
.ai/skills/requesting-code-review/code-reviewer.md is missing a language
identifier (causing MD040); update the opening triple-backticks for that example
block fromtomarkdown (or ```text) so the linter recognizes the
language, then re-run the markdown linter to confirm the MD040 violation is
resolved.</details> </blockquote></details> <details> <summary>.ai/skills/verification-before-completion/SKILL.md-18-20 (1)</summary><blockquote> `18-20`: _⚠️ Potential issue_ | _🟡 Minor_ **Standardize fenced code block languages to clear MD040 warnings.** At **Line 18**, **Line 26**, **Line 79**, **Line 85**, **Line 91**, **Line 97**, and **Line 103**, fences are missing language tags. Add `text` where these are illustrative snippets. Also applies to: 26-38, 79-82, 85-88, 91-94, 97-100, 103-106 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/verification-before-completion/SKILL.md around lines 18 - 20,
Several fenced code blocks in SKILL.md are missing language tags (e.g., the
block containing "NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE" and
other illustrative snippets); update each triple-backtick fence used for
illustrative text to use thetextlanguage tag so Markdown linters (MD040)
stop flagging them—search for all untaggedblocks in the file and change
to ```text for the snippets around those sections.</details> </blockquote></details> <details> <summary>.ai/skills/systematic-debugging/root-cause-tracing.md-88-90 (1)</summary><blockquote> `88-90`: _⚠️ Potential issue_ | _🟡 Minor_ **Make test command example consistent with Bun-based workflow.** At **Line 89**, `npm test` is likely inconsistent with the repository’s Bun-first workflow. Prefer a Bun command example here to avoid confusion when users copy-paste. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/systematic-debugging/root-cause-tracing.md around lines 88 - 90, Replace the npm-based test example command "npm test 2>&1 | grep 'DEBUG git init'" with the Bun equivalent to match the Bun-first workflow; update the string to use "bun test 2>&1 | grep 'DEBUG git init'" (keep the same redirection and grep filter) wherever this example command appears so examples and docs are consistent with Bun tooling. ``` </details> </blockquote></details> <details> <summary>.ai/skills/writing-plans/plan-document-reviewer-prompt.md-9-47 (1)</summary><blockquote> `9-47`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language identifier to the fenced block for lint compliance.** At **Line 9**, the code fence is untyped, which triggers MD040 in markdownlint. Use a language label (e.g., `text`). <details> <summary>Suggested diff</summary> ```diff -``` +```text Task tool (general-purpose): description: "Review plan document" prompt: | @@ -``` +``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/writing-plans/plan-document-reviewer-prompt.md around lines 9 -
47, In the Task tool (general-purpose) prompt block in
.ai/skills/writing-plans/plan-document-reviewer-prompt.md, the fenced code block
around the YAML prompt is missing a language identifier which triggers
markdownlint rule MD040; update the opening triple-backtick to include a
language (for example changetotext) so the fenced block is typed and
lint-compliant, leaving the rest of the block (the "Task tool
(general-purpose):" description and the prompt content) unchanged.</details> </blockquote></details> <details> <summary>.ai/skills/finishing-a-development-branch/SKILL.md-154-159 (1)</summary><blockquote> `154-159`: _⚠️ Potential issue_ | _🟡 Minor_ **Inconsistency between table and text for Option 2 worktree handling.** The quick reference table shows Option 2 (Create PR) keeps the worktree (`✓`), but lines 106 and 138 indicate worktree cleanup happens for Options 1, 2, and 4. Additionally, line 173 states "Only cleanup for Options 1 and 4", omitting Option 2. Please clarify the intended behavior: should Option 2 (Push and Create PR) preserve or remove the worktree? <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/finishing-a-development-branch/SKILL.md around lines 154 - 159, Decide that Option 2 (Create PR) should preserve the worktree, then make the doc consistent: update the quick-reference table row for "2. Create PR" so the "Keep Worktree" column is ✓; change the text that currently lists "Options 1, 2, and 4" for worktree cleanup to remove Option 2 (so it reads only Options 1 and 4), and update the later sentence that currently omits Option 2 (around the "Only cleanup for Options 1 and 4" paragraph) to match the table; ensure any mention of forced cleanup for "Discard" (Option 4) remains clear. ``` </details> </blockquote></details> <details> <summary>.ai/skills/test-driven-development/SKILL.md-359-362 (1)</summary><blockquote> `359-362`: _⚠️ Potential issue_ | _🟡 Minor_ **The reference to `@testing-anti-patterns.md` is broken—this file does not exist in the repository.** Either create the `@testing-anti-patterns.md` file with the anti-patterns guidance mentioned (testing mock behavior instead of real behavior, adding test-only methods to production classes, mocking without understanding dependencies), or remove/update the reference to point to existing documentation. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/test-driven-development/SKILL.md around lines 359 - 362, The SKILL.md file references a non-existent document "@testing-anti-patterns.md"; either add that file to the repo with the three anti-patterns described (testing mock behavior instead of real behavior, adding test-only methods to production classes, mocking without understanding dependencies) or change the reference in .ai/skills/test-driven-development/SKILL.md to point to an existing doc or inline the guidance there—update the string "@testing-anti-patterns.md" accordingly so the link/reference resolves. ``` </details> </blockquote></details> <details> <summary>.ai/skills/writing-skills/SKILL.md-286-289 (1)</summary><blockquote> `286-289`: _⚠️ Potential issue_ | _🟡 Minor_ **Inconsistent guidance on @ link usage.** Lines 286-288 warn against using `@` syntax because it "force-loads files immediately, consuming 200k+ context," but line 556 uses `@testing-skills-with-subagents.md`. Consider either removing the @ prefix at line 556 or clarifying when @ links are acceptable. <details> <summary>Suggested fix for line 556</summary> ```diff -**Testing methodology:** See `@testing-skills-with-subagents.md` for the complete testing methodology: +**Testing methodology:** See `testing-skills-with-subagents.md` in this directory for the complete testing methodology: ``` </details> Also applies to: 556-557 <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/writing-skills/SKILL.md around lines 286 - 289, The doc is inconsistent about using the `@` prefix: earlier guidance in SKILL.md warns that `@` force-loads files and consumes large context, but later a link uses `@testing-skills-with-subagents.md`; update SKILL.md to make the rule consistent by either (A) removing the `@` prefix from the later link `@testing-skills-with-subagents.md` so it becomes a normal relative link, or (B) add a clarifying sentence near the earlier warning describing the specific acceptable use-case for `@` links (e.g., only for immediate preload of critical files) and annotate `@testing-skills-with-subagents.md` with why it’s acceptable; change the link text (or the warning paragraph) accordingly to keep behavior and guidance aligned. ``` </details> </blockquote></details> <details> <summary>.ai/skills/brainstorming/scripts/helper.js-14-19 (1)</summary><blockquote> `14-19`: _⚠️ Potential issue_ | _🟡 Minor_ **Add error handling for JSON.parse.** If the server sends malformed JSON, `JSON.parse(msg.data)` will throw an uncaught exception, potentially breaking the WebSocket handler. <details> <summary>Suggested fix</summary> ```diff ws.onmessage = (msg) => { - const data = JSON.parse(msg.data); - if (data.type === 'reload') { - window.location.reload(); + try { + const data = JSON.parse(msg.data); + if (data.type === 'reload') { + window.location.reload(); + } + } catch (e) { + console.warn('Invalid JSON from WebSocket:', e); } }; ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/brainstorming/scripts/helper.js around lines 14 - 19, Wrap the JSON.parse call inside the ws.onmessage handler in a try/catch to prevent malformed JSON from throwing and breaking the WebSocket handler; catch the error in the onmessage callback (ws.onmessage), log or console.warn the parse error along with the raw msg.data for debugging, and return/ignore that message so only well-formed messages (e.g., where data.type === 'reload') are processed. ``` </details> </blockquote></details> <details> <summary>.ai/skills/writing-skills/SKILL.md-635-645 (1)</summary><blockquote> `635-645`: _⚠️ Potential issue_ | _🟡 Minor_ **Numbering sequence error in Discovery Workflow.** The numbered list skips from 1 to 3, missing step 2. <details> <summary>Suggested fix</summary> ```diff ## Discovery Workflow How future Claude finds your skill: 1. **Encounters problem** ("tests are flaky") -3. **Finds SKILL** (description matches) -4. **Scans overview** (is this relevant?) -5. **Reads patterns** (quick reference table) -6. **Loads example** (only when implementing) +2. **Finds SKILL** (description matches) +3. **Scans overview** (is this relevant?) +4. **Reads patterns** (quick reference table) +5. **Loads example** (only when implementing) ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/writing-skills/SKILL.md around lines 635 - 645, The numbered list under the "Discovery Workflow" header has a sequence gap (it jumps from 1 to 3); renumber the list items so they read 1 through 6 in order — change "Finds SKILL" from 3 to 2 and shift "Scans overview", "Reads patterns", and "Loads example" to 3, 4, and 5 respectively (ensure the final item is 6), leaving the "Optimize for this flow" sentence after the list; update the list numbering in the Discovery Workflow section accordingly. ``` </details> </blockquote></details> <details> <summary>.ai/skills/brainstorming/scripts/helper.js-56-60 (1)</summary><blockquote> `56-60`: _⚠️ Potential issue_ | _🟡 Minor_ **Potential XSS via innerHTML with dynamic content.** Lines 57 and 59 use `innerHTML` with content derived from `label` (which comes from DOM element text content). If card labels could contain user-generated content, this creates an XSS vector. Consider using `textContent` for the label portion. <details> <summary>Suggested fix</summary> ```diff } else if (selected.length === 1) { const label = selected[0].querySelector('h3, .content h3, .card-body h3')?.textContent?.trim() || selected[0].dataset.choice; - indicator.innerHTML = '<span class="selected-text">' + label + ' selected</span> — return to terminal to continue'; + indicator.textContent = ''; + const span = document.createElement('span'); + span.className = 'selected-text'; + span.textContent = label + ' selected'; + indicator.appendChild(span); + indicator.appendChild(document.createTextNode(' — return to terminal to continue')); } else { - indicator.innerHTML = '<span class="selected-text">' + selected.length + ' selected</span> — return to terminal to continue'; + indicator.textContent = ''; + const span = document.createElement('span'); + span.className = 'selected-text'; + span.textContent = selected.length + ' selected'; + indicator.appendChild(span); + indicator.appendChild(document.createTextNode(' — return to terminal to continue')); } ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/brainstorming/scripts/helper.js around lines 56 - 60, The code uses indicator.innerHTML with dynamic label content (variable label derived from selected[0].querySelector(...).textContent or dataset.choice), creating an XSS risk; update the block that sets indicator.innerHTML (references: label, selected, indicator) to avoid injecting unescaped HTML by creating the span element programmatically, setting its textContent to the label or selected.length, and then appending the rest of the static text nodes (e.g., " selected — return to terminal to continue") rather than concatenating strings into innerHTML; ensure both the single-selection and multi-selection branches follow this safe DOM construction approach. ``` </details> </blockquote></details> <details> <summary>.ai/skills/brainstorming/scripts/start-server.sh-100-100 (1)</summary><blockquote> `100-100`: _⚠️ Potential issue_ | _🟡 Minor_ **Handle potential `cd` failure.** If `cd "$SCRIPT_DIR"` fails (e.g., directory was deleted), the script will continue and attempt to run `node server.cjs` from an unexpected directory, leading to confusing errors. <details> <summary>🛡️ Proposed fix</summary> ```diff -cd "$SCRIPT_DIR" +cd "$SCRIPT_DIR" || { echo '{"error": "Failed to change to script directory"}'; exit 1; } ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/brainstorming/scripts/start-server.sh at line 100, Ensure the script checks the result of the cd "$SCRIPT_DIR" command and exits with a clear error if it fails: after the cd "$SCRIPT_DIR" in start-server.sh, verify the directory change succeeded (or test -d "$SCRIPT_DIR" beforehand) and if not, print an error mentioning "$SCRIPT_DIR" and stop the script (exit non‑zero) before attempting to run node server.cjs so the server is never started from the wrong directory. ``` </details> </blockquote></details> <details> <summary>.ai/memory/topics/auth-flow.md-25-25 (1)</summary><blockquote> `25-25`: _⚠️ Potential issue_ | _🟡 Minor_ **Use the concrete listener symbol name from implementation.** Line 25 points to `createCallbackListener`, but the implementation entrypoint shown in `apps/cli/src/lib/login.ts` is `createLoopbackCallbackListener()`. Aligning the name will reduce lookup friction. <details> <summary>Suggested patch</summary> ```diff -1. `mdcms login` starts a local HTTP listener (`createCallbackListener` in `apps/cli/src/lib/login.ts`) bound to `127.0.0.1` on an ephemeral port. Callback path is `/callback`. +1. `mdcms login` starts a local HTTP listener (`createLoopbackCallbackListener` in `apps/cli/src/lib/login.ts`) bound to `127.0.0.1` on an ephemeral port. Callback path is `/callback`. ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/memory/topics/auth-flow.md at line 25, Update the documented listener symbol name to match the implementation: replace references to createCallbackListener with the concrete implementation name createLoopbackCallbackListener (the entrypoint used in the login flow implementation) and scan for other mismatched occurrences to ensure the docs/comments use the exact symbol from apps/cli/src/lib/login.ts. ``` </details> </blockquote></details> <details> <summary>.ai/skills/dispatching-parallel-agents/SKILL.md-145-149 (1)</summary><blockquote> `145-149`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language to the fenced code block (MD040).** The block starting at Line 145 is missing a fence language, which trips markdownlint. <details> <summary>Suggested patch</summary> ```diff -``` +```text Agent 1 → Fix agent-tool-abort.test.ts Agent 2 → Fix batch-completion-behavior.test.ts Agent 3 → Fix tool-approval-race-conditions.test.ts ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/dispatching-parallel-agents/SKILL.md around lines 145 - 149, The
fenced code block containing the three "Agent 1 → ..." lines is missing a
language specifier and triggers markdownlint MD040; update the opening fence
fromto a language-tagged fence (e.g.,text) for the block that contains
"Agent 1 → Fix agent-tool-abort.test.ts", "Agent 2 → Fix
batch-completion-behavior.test.ts", and "Agent 3 → Fix
tool-approval-race-conditions.test.ts" so the block is recognized as a code
block with a language.</details> </blockquote></details> </blockquote></details> <details> <summary>🧹 Nitpick comments (16)</summary><blockquote> <details> <summary>.ai/skills/brainstorming/scripts/frame-template.html (1)</summary><blockquote> `118-144`: **Add keyboard focus-visible styles for interactive patterns.** `.option` and `.card` have hover/selected states but no explicit keyboard focus affordance. <details> <summary>Suggested change</summary> ```diff .option:hover { border-color: var(--accent); } +.option:focus-visible { + outline: 2px solid var(--accent); + outline-offset: 2px; +} .option.selected { background: var(--selected-bg); border-color: var(--selected-border); } .card:hover { border-color: var(--accent); transform: translateY(-2px); box-shadow: 0 4px 12px rgba(0,0,0,0.1); } +.card:focus-visible { + outline: 2px solid var(--accent); + outline-offset: 2px; +} .card.selected { border-color: var(--selected-border); border-width: 2px; } ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/brainstorming/scripts/frame-template.html around lines 118 - 144, Add explicit keyboard focus affordances for the interactive patterns by adding :focus-visible rules for .option and .card (e.g., .option:focus-visible and .card:focus-visible) that mirror the hover/selected styling (distinct border-color, outline or box-shadow) so keyboard users can see focus; also ensure the interactive elements that use .option and .card are keyboard-focusable (add tabindex where they are non-interactive elements) and keep consistency with the selected state (.option.selected and .card.selected) so focus-visible doesn't clash with selection visuals. ``` </details> </blockquote></details> <details> <summary>.ai/skills/systematic-debugging/test-pressure-2.md (1)</summary><blockquote> `12-16`: **Add language identifier to fenced code block.** The error message code block should include a language identifier for proper syntax highlighting and Markdown linting compliance. <details> <summary>📝 Proposed fix</summary> ```diff -``` +```text Expected: { status: 'completed', amount: 100 } Received: { status: 'pending', amount: 100 } ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/systematic-debugging/test-pressure-2.md around lines 12 - 16, Add
a language identifier to the fenced code block containing the error message so
Markdown linters and syntax highlighters recognize it; update the opening fence
fromtotext for the block that currently reads "" followed by "Expected: { status: 'completed', amount: 100 } Received: { status: 'pending', amount: 100 }" (the fenced code block in .ai/skills/systematic-debugging/test-pressure-2.md) so it becomes "text" and
keep the closing fence unchanged.</details> </blockquote></details> <details> <summary>.ai/memory/integrations/README.md (1)</summary><blockquote> `9-9`: **Capitalize "GitHub" per official branding.** The directory path reference uses lowercase "github" but the official brand name is "GitHub" with a capital "H". <details> <summary>📝 Proposed capitalization fix</summary> ```diff -- [`github-actions.md`](github-actions.md) — CI gates and workflow files in `.github/workflows/`. +- [`github-actions.md`](github-actions.md) — CI gates and workflow files in `.github/workflows/`. ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/memory/integrations/README.md at line 9, Update the capitalization of the GitHub brand in the README entry: change the link text [`github-actions.md`] and the directory reference `.github/workflows/` so the brand reads "GitHub" (e.g., display as "GitHub Actions" or ensure "GitHub" is capitalized while keeping the target link `github-actions.md`), ensuring the visible text uses the official "GitHub" capitalization. ``` </details> </blockquote></details> <details> <summary>.ai/LANGUAGE.md (1)</summary><blockquote> `11-11`: **Resolve the “property” self-contradiction in the Field row.** Line 11 defines Field using “property” but also forbids saying “property,” which weakens the rule clarity. Consider rewording the meaning to avoid disallowed synonyms. <details> <summary>Suggested fix</summary> ```diff -| **Field** | A typed property on a content type | column, attribute, property | +| **Field** | A typed value defined on a content type | column, attribute, property | ``` </details> Based on learnings: Use `.ai/LANGUAGE.md` for naming conventions; do not invent synonyms for existing terms. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/LANGUAGE.md at line 11, The Field table row currently uses the disallowed synonym "property" both in the definition and in the synonyms column; update the Field entry so the definition avoids the word "property" (e.g., "A typed attribute on a content type") and remove "property" from the third-column synonyms list (leave allowed terms like "column, attribute" or similar approved synonyms), editing the table row that begins with "**Field**" to reflect this wording change. ``` </details> </blockquote></details> <details> <summary>.ai/skills/brainstorming/SKILL.md (1)</summary><blockquote> `163-165`: **Consider clarifying the relative path to visual-companion.md.** The path `skills/brainstorming/visual-companion.md` may be ambiguous depending on the skill resolution context. Consider using a relative path from the current file: ```diff -`skills/brainstorming/visual-companion.md` +`./visual-companion.md` ``` <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/brainstorming/SKILL.md around lines 163 - 165, Update the ambiguous link path in SKILL.md so it uses a clear relative path from the current file location: replace the reference `skills/brainstorming/visual-companion.md` with `./visual-companion.md` in the sentence inside .ai/skills/brainstorming/SKILL.md to ensure the resolver finds the file in the same directory. ``` </details> </blockquote></details> <details> <summary>.ai/skills/finishing-a-development-branch/SKILL.md (1)</summary><blockquote> `28-34`: **Consider adding language specifiers to fenced code blocks.** Markdownlint flags these as missing language specifiers. For text/output blocks, use `text` or `plaintext`: <details> <summary>Suggested fix</summary> ```diff -``` +```text Tests failing (<N> failures). Must fix before completing: ``` </details> This also applies to lines 53-62 and 117-124. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/finishing-a-development-branch/SKILL.md around lines 28 - 34, The
fenced code blocks in SKILL.md that contain plain test/output snippets (for
example the block starting with "Tests failing ( failures). Must fix before
completing:" and the other similar blocks referenced in the comment) are missing
language specifiers; update each opening triple-backtick to include a language
specifier such astext (orplaintext) so markdownlint stops flagging
them—locate the blocks by the exact snippet text and change their opening fences
to ```text.</details> </blockquote></details> <details> <summary>.ai/skills/writing-skills/examples/CLAUDE_MD_TESTING.md (1)</summary><blockquote> `8-8`: **Add language specifiers to fenced code blocks.** The scenario blocks would be more semantically correct with a language identifier. Consider using `text` or leaving the blocks as plain text quote blocks. <details> <summary>📝 Proposed fix</summary> ```diff -``` +```text IMPORTANT: This is a real scenario. Choose and act. ``` Apply this pattern to all four scenario blocks (lines 8, 22, 39, 53). </details> Also applies to: 22-22, 39-39, 53-53 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/writing-skills/examples/CLAUDE_MD_TESTING.md at line 8, Add a
language specifier ("text") to each of the fenced scenario code blocks in the
document so they becometext ...instead of plain ```; specifically
update all four scenario blocks (the fenced blocks that begin with the scenario
text) so they include the language identifier to improve semantics and syntax
highlighting.</details> </blockquote></details> <details> <summary>.ai/skills/brainstorming/scripts/helper.js (1)</summary><blockquote> `21-24`: **Consider exponential backoff for WebSocket reconnection.** The fixed 1-second reconnect delay could cause rapid reconnection attempts if the server is down for an extended period. Exponential backoff would reduce load during outages. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In @.ai/skills/brainstorming/scripts/helper.js around lines 21 - 24, The ws.onclose handler currently calls setTimeout(connect, 1000) causing a fixed 1s retry; replace this with an exponential backoff: introduce a module-level reconnectDelay (initial e.g. 1000), backoffFactor (e.g. 2) and maxDelay (e.g. 30000), call setTimeout(connect, reconnectDelay) in ws.onclose (or the reconnect path) and after scheduling multiply reconnectDelay = Math.min(reconnectDelay * backoffFactor, maxDelay); also reset reconnectDelay to the initial value in the successful connection handler (ws.onopen or inside connect after success) so retries start fast again; update functions/variables referenced such as ws.onclose, connect, ws.onopen to use this backoff logic. ``` </details> </blockquote></details> <details> <summary>.ai/skills/systematic-debugging/SKILL.md (1)</summary><blockquote> `77-87`: **Consider `text` language specifier for pseudocode blocks.** The diagnostic instrumentation pseudocode block at line 77 lacks a language identifier. Using `text` would satisfy markdownlint while preserving readability. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/systematic-debugging/SKILL.md around lines 77 - 87, The fenced
pseudocode block starting with "For EACH component boundary:" should include a
language specifier to satisfy markdownlint; edit that triple-backtick fence in
SKILL.md so it reads ```text (i.e., add the "text" language tag) to the block
containing the diagnostic instrumentation pseudocode to preserve readability and
fix the lint warning.</details> </blockquote></details> <details> <summary>.ai/skills/receiving-code-review/SKILL.md (1)</summary><blockquote> `16-26`: **Consider adding language specifiers to pseudocode blocks.** Multiple fenced code blocks in this file lack language identifiers (lines 16, 42, 51, 68, 90, 102, 134, 153, etc.), triggering markdownlint MD040 warnings. For pseudocode/structured text blocks, consider using `text` or `plaintext` as the language identifier to satisfy linters while keeping the blocks visually distinct. <details> <summary>Example fix for line 16</summary> ```diff -``` +```text WHEN receiving code review feedback: 1. READ: Complete feedback without reacting ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/receiving-code-review/SKILL.md around lines 16 - 26, Several
fenced pseudocode blocks in SKILL.md (e.g., the block starting with "WHEN
receiving code review feedback:" and the other blocks shown around lines noted
in the review) are missing language specifiers and trigger markdownlint MD040;
update each fenced code block by adding a language identifier such as text or
plaintext (e.g., changetotext) so linters accept them, ensuring you
modify every fenced block in the file (including blocks at the top and those
around the other listed examples) while preserving the original content and
formatting.</details> </blockquote></details> <details> <summary>.ai/skills/subagent-driven-development/SKILL.md (1)</summary><blockquote> `128-200`: **Consider `text` language specifier for example workflow.** The example workflow block at line 128 lacks a language identifier. Using `text` would satisfy markdownlint MD040. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/subagent-driven-development/SKILL.md around lines 128 - 200, The
fenced example workflow block that begins with "You: I'm using Subagent-Driven
Development to execute this plan." is missing a language specifier; add "text"
immediately after the opening(i.e. changeto ```text) to satisfy
markdownlint MD040, and scan other fenced blocks in the same SKILL.md section
(e.g., the workflow example) to ensure they also include an explicit language
tag.</details> </blockquote></details> <details> <summary>.ai/skills/writing-skills/anthropic-best-practices.md (1)</summary><blockquote> `257-267`: **Add language specifiers to directory structure code blocks.** The static analysis tool flagged three fenced code blocks without language specifiers (lines 257, 301, 1040). Adding a language identifier improves rendering consistency across Markdown viewers. <details> <summary>📝 Proposed fix</summary> For directory structure blocks, use `text` or `plaintext`: ```diff -``` +```text pdf/ ├── SKILL.md # Main instructions (loaded when triggered) ``` Apply similar changes to the code blocks at lines 301 and 1040. </details> Also applies to: 301-309, 1040-1047 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/skills/writing-skills/anthropic-best-practices.md around lines 257 -
267, Add language specifiers to the three fenced code blocks that show directory
trees (the block starting with "pdf/" listing SKILL.md, FORMS.md, reference.md,
examples.md and scripts/) and the two other similar directory-structure blocks
flagged by static analysis; change their opening fences fromtotext (orconsistent across viewers..ai/skills/brainstorming/scripts/server.cjs (2)
101-103: Consider graceful handling for missing template files.If
frame-template.htmlorhelper.jsis missing at startup, the server will crash with a genericENOENTerror. A more descriptive error message would help debugging.📝 Proposed improvement
-const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8'); -const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8'); +let frameTemplate, helperScript; +try { + frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8'); + helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8'); +} catch (e) { + console.error(JSON.stringify({ type: 'startup-error', error: `Missing required file: ${e.path}` })); + process.exit(1); +}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.ai/skills/brainstorming/scripts/server.cjs around lines 101 - 103, The code reads frame-template.html and helper.js into frameTemplate and helperScript using fs.readFileSync which will throw ENOENT if files are missing; wrap those reads (the creation of frameTemplate, helperScript and helperInjection) in a guarded check or try/catch in server.cjs so you can log a descriptive error (including the missing filename and error.message) and either provide a safe fallback or exit gracefully; update any code that constructs helperInjection to only do so after helperScript is successfully loaded.
289-290: Minor TOCTOU race in events file deletion.There's a small race window between
fs.existsSync(eventsFile)andfs.unlinkSync(eventsFile)if another process deletes the file in between. Using a try-catch would be more robust.📝 Proposed fix
if (!knownFiles.has(filename)) { knownFiles.add(filename); const eventsFile = path.join(STATE_DIR, 'events'); - if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile); + try { fs.unlinkSync(eventsFile); } catch (e) { if (e.code !== 'ENOENT') throw e; } console.log(JSON.stringify({ type: 'screen-added', file: filePath }));🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.ai/skills/brainstorming/scripts/server.cjs around lines 289 - 290, Replace the TOCTOU pattern around eventsFile (constructed from STATE_DIR and 'events') by removing the fs.existsSync check and attempting to delete inside a try-catch: call fs.unlinkSync(eventsFile) (or fs.rmSync with force:true) and catch errors, ignoring only ENOENT (file-not-found) while re-throwing other errors so concurrent deletions don't crash the process..ai/memory/topics/schema-sync.md (1)
16-16: Clarify decision criteria for “migrated lazily or rejected.”This sentence is helpful but currently broad; consider naming the exact rule source (spec/ADR section) that determines which path is used for a given change class.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.ai/memory/topics/schema-sync.md at line 16, Update the sentence "Documents authored against an old hash get migrated lazily or rejected based on the change type" to explicitly state the decision rule and point to the authoritative source; replace the vague phrase with a short rule summary (e.g., "backwards-compatible additive changes → lazy migration; breaking or incompatible changes → rejection") and add a parenthetical reference to the exact spec/ADR section or filename (for example ADR-002 or "spec/schema-migration.md" as applicable) so readers know which document defines the classification and behavior..ai/skills/executing-plans/SKILL.md (1)
16-38: Make the worktree prerequisite explicit in the execution steps.
superpowers:using-git-worktreesis marked REQUIRED (Line 68), but the process flow starts directly at plan review/execution. Add a Step 0 so agents can’t skip isolation accidentally.Suggested patch
## The Process +### Step 0: Prepare isolated workspace +1. **REQUIRED SUB-SKILL:** Use `superpowers:using-git-worktrees` +2. Confirm you're not on `main`/`master` +3. Then continue to Step 1 + ### Step 1: Load and Review Plan 1. Read plan file 2. Review critically - identify any questions or concerns about the planAlso applies to: 67-70
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.ai/skills/executing-plans/SKILL.md around lines 16 - 38, Add a new Step 0 in the "The Process" section of SKILL.md that makes the worktree prerequisite explicit: require agents to run the superpowers:using-git-worktrees setup (isolation via git worktree) before Step 1 (Load and Review Plan), so they cannot start plan review/execution without creating an isolated worktree; update references that currently mark superpowers:using-git-worktrees as REQUIRED and ensure the finishing-a-development-branch sub-skill still remains invoked in Step 3.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: b0794bd9-4722-4c63-b0bc-f4b3b09a227f
⛔ Files ignored due to path filters (1)
.ai/skills/writing-skills/graphviz-conventions.dotis excluded by!**/*.dot
📒 Files selected for processing (78)
.agents/skills.ai/LANGUAGE.md.ai/memory/README.md.ai/memory/architecture.md.ai/memory/initiatives/README.md.ai/memory/integrations/README.md.ai/memory/integrations/docker-stack.md.ai/memory/integrations/github-actions.md.ai/memory/integrations/nx-mcp.md.ai/memory/lessons.md.ai/memory/product.md.ai/memory/stack.md.ai/memory/topics/README.md.ai/memory/topics/auth-flow.md.ai/memory/topics/module-system.md.ai/memory/topics/multi-tenancy.md.ai/memory/topics/push-pull-sync.md.ai/memory/topics/schema-sync.md.ai/plans/.gitkeep.ai/research/.gitkeep.ai/skills/LICENSE.superpowers.ai/skills/README.md.ai/skills/brainstorming/SKILL.md.ai/skills/brainstorming/scripts/frame-template.html.ai/skills/brainstorming/scripts/helper.js.ai/skills/brainstorming/scripts/server.cjs.ai/skills/brainstorming/scripts/start-server.sh.ai/skills/brainstorming/scripts/stop-server.sh.ai/skills/brainstorming/spec-document-reviewer-prompt.md.ai/skills/brainstorming/visual-companion.md.ai/skills/dispatching-parallel-agents/SKILL.md.ai/skills/executing-plans/SKILL.md.ai/skills/finishing-a-development-branch/SKILL.md.ai/skills/receiving-code-review/SKILL.md.ai/skills/requesting-code-review/SKILL.md.ai/skills/requesting-code-review/code-reviewer.md.ai/skills/subagent-driven-development/SKILL.md.ai/skills/subagent-driven-development/code-quality-reviewer-prompt.md.ai/skills/subagent-driven-development/implementer-prompt.md.ai/skills/subagent-driven-development/spec-reviewer-prompt.md.ai/skills/systematic-debugging/CREATION-LOG.md.ai/skills/systematic-debugging/SKILL.md.ai/skills/systematic-debugging/condition-based-waiting-example.ts.ai/skills/systematic-debugging/condition-based-waiting.md.ai/skills/systematic-debugging/defense-in-depth.md.ai/skills/systematic-debugging/find-polluter.sh.ai/skills/systematic-debugging/root-cause-tracing.md.ai/skills/systematic-debugging/test-academic.md.ai/skills/systematic-debugging/test-pressure-1.md.ai/skills/systematic-debugging/test-pressure-2.md.ai/skills/systematic-debugging/test-pressure-3.md.ai/skills/test-driven-development/SKILL.md.ai/skills/test-driven-development/testing-anti-patterns.md.ai/skills/using-git-worktrees/SKILL.md.ai/skills/using-superpowers/SKILL.md.ai/skills/using-superpowers/references/codex-tools.md.ai/skills/using-superpowers/references/copilot-tools.md.ai/skills/using-superpowers/references/gemini-tools.md.ai/skills/verification-before-completion/SKILL.md.ai/skills/writing-plans/SKILL.md.ai/skills/writing-plans/plan-document-reviewer-prompt.md.ai/skills/writing-skills/SKILL.md.ai/skills/writing-skills/anthropic-best-practices.md.ai/skills/writing-skills/examples/CLAUDE_MD_TESTING.md.ai/skills/writing-skills/persuasion-principles.md.ai/skills/writing-skills/render-graphs.js.ai/skills/writing-skills/testing-skills-with-subagents.md.claude/settings.json.claude/skills.codex/config.toml.cursor/skills.gitignore.prettierignoreAGENTS.mdCLAUDE.mdapps/cli/AGENTS.mdapps/server/AGENTS.mddocs/specs/SPEC-013-mintlify-docs-site.md
There was a problem hiding this comment.
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 @.ai/memory/README.md:
- Around line 21-34: The fenced diagram block in .ai/memory/README.md that
begins with the lines "First-time / onboarding" and shows the
onboarding/feature/debugging flows is missing a language tag and triggers MD040;
add a language identifier (for example, text) to the opening triple-backtick so
the block becomes "```text" to satisfy markdown linting and formatting rules.
In `@AGENTS.md`:
- Around line 111-125: The unlabeled fenced code block that renders the .ai/
directory tree should be changed to a labeled fenced block to satisfy MD040;
update the snippet that begins with ".ai/" (the directory tree showing
LANGUAGE.md, plans/, research/, memory/, skills/) by adding the language tag
"text" after the opening backticks so the block becomes a ```text fenced block.
🪄 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 Plus
Run ID: 15d91a07-f355-425c-8a74-c25cd30b60b6
📒 Files selected for processing (3)
.ai/memory/README.md.ai/memory/integrations/README.mdAGENTS.md
…docs
`ROADMAP_TASKS.md` is a local-only file that doesn't exist on a fresh
clone. Per the principle that committed docs must make sense for any
contributor, removing every reference to it from `AGENTS.md`,
`.ai/memory/README.md`, `.ai/memory/architecture.md`, and
`.ai/memory/initiatives/README.md`.
Replacements use generic phrasing ("the issue tracker", "the linked
issue", "task's acceptance criteria") so the rules still apply
regardless of which planning tool the team happens to use.
The `.gitignore` entry for `ROADMAP_TASKS.md` stays — that's the
mechanism that keeps it from being committed accidentally; nothing in
committed docs references it anymore.
There was a problem hiding this comment.
♻️ Duplicate comments (2)
AGENTS.md (1)
110-124:⚠️ Potential issue | 🟡 MinorAdd a language tag to the
.ai/tree snippet fence.The
.ai/directory tree block starts at Line 110 with bareand ends at Line 124 with bare. Add a language tag (e.g.,```text) to satisfy markdownlint rules (MD040-style).Suggested patch
-``` +```text .ai/ ├── LANGUAGE.md # Project vocabulary — use these names, don't coin new ones ├── plans/ # Implementation plans (committed; populated as new work happens) ├── research/ # Research artifacts (date-prefixed) ├── memory/ # Team product memory (see .ai/memory/README.md) │ ├── product.md # Vision, audience, scope │ ├── architecture.md # System patterns, invariants, hard rules │ ├── stack.md # Runtime, deps, infrastructure │ ├── lessons.md # Append-only dev-time pitfalls │ ├── topics/ # Cross-cutting domain knowledge (auth, sync, multi-tenancy, …) │ ├── integrations/ # External systems (Docker, CI) │ └── initiatives/ # One file per major team effort └── skills/ # Vendored superpowers + project-local skills</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@AGENTS.mdaround lines 110 - 124, The fenced code block showing the .ai/
directory tree uses bare triple backticks; update the opening fence to include a
language tag (for example changetotext) so the block beginning with
".ai/" and its closing ``` satisfy markdownlint MD040; ensure only the opening
fence is modified and the block content and closing fence remain unchanged.</details> </blockquote></details> <details> <summary>.ai/memory/README.md (1)</summary><blockquote> `21-34`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language tag to the fenced onboarding diagram block.** The fenced block starting at Line 21 uses bare ``` (no language), which commonly triggers markdownlint (e.g., MD040). Change the opening fence to ` ```text ` (or another appropriate language) and keep the closing fence unchanged. <details> <summary>Suggested patch</summary> ```diff -``` +```text First-time / onboarding └─ product.md → architecture.md → stack.md → skim topics/ index → skim initiatives/ active Starting a feature └─ architecture.md (invariants) → topics/ (relevant cross-cutting) → initiatives/ (does this fit something?) → docs/specs/<owning>.md (canonical scope, NOT in memory/) Debugging a thing that broke └─ lessons.md (have we seen this?) → topics/ (cross-cutting flow) → integrations/ (external system?) Wondering why something is the way it is └─ architecture.md (patterns) → docs/adrs/ (decision rationale) → initiatives/ (which effort drove this?) ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.ai/memory/README.md around lines 21 - 34, The fenced onboarding diagram
block that begins with the line "First-time / onboarding" uses a bare triple
backtick; update its opening fence fromtotext (leave the closing fence
unchanged) so the block is explicitly marked as plain text and markdownlint
MD040 is satisfied.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In @.ai/memory/README.md:
- Around line 21-34: The fenced onboarding diagram block that begins with the
line "First-time / onboarding" uses a bare triple backtick; update its opening
fence fromtotext (leave the closing fence unchanged) so the block is
explicitly marked as plain text and markdownlint MD040 is satisfied.In
@AGENTS.md:
- Around line 110-124: The fenced code block showing the .ai/ directory tree
uses bare triple backticks; update the opening fence to include a language tag
(for example changetotext) so the block beginning with ".ai/" and its
closing ``` satisfy markdownlint MD040; ensure only the opening fence is
modified and the block content and closing fence remain unchanged.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro Plus **Run ID**: `1b38aba5-ff34-4a7e-a751-94f7945e1b34` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 806d62d4f17cc26d2123d5192707a9f25de5eba7 and af00522af2b41d107bd4cb661c2e626e509f2a25. </details> <details> <summary>📒 Files selected for processing (4)</summary> * `.ai/memory/README.md` * `.ai/memory/architecture.md` * `.ai/memory/initiatives/README.md` * `AGENTS.md` </details> <details> <summary>✅ Files skipped from review due to trivial changes (1)</summary> * .ai/memory/initiatives/README.md </details> <details> <summary>🚧 Files skipped from review as they are similar to previous changes (1)</summary> * .ai/memory/architecture.md </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
CodeRabbit flagged MD040 on the unlabeled fenced blocks containing the `.ai/` directory tree (AGENTS.md) and the agent reading-order diagram (memory/README.md). Adding the `text` language tag — purely a lint fix, no content change.
There was a problem hiding this comment.
🧹 Nitpick comments (3)
AGENTS.md (2)
205-212: Style nit: repeated “Keep …” bullet starts are flagged by LanguageTool.
The “Package boundary rules” bullet list uses multiple successive “Keep …” starts; LanguageTool is warning on the repeated phrasing. This likely won’t break anything, but if CI includes LanguageTool/style checks, consider rewording 1–2 bullets to avoid the pattern.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@AGENTS.md` around lines 205 - 212, The bulleted list under "Package boundary rules" repeats the phrase "Keep ..." and triggers style checks; update 1–2 bullets (e.g., the lines referencing `@mdcms/shared`, `@mdcms/cli`, `@mdcms/sdk`, `@mdcms/studio`, `@mdcms/server`) to vary phrasing while preserving meaning—replace "Keep" with alternatives like "Place", "Contain", or "Handle" for some entries and ensure each package name (e.g., `@mdcms/shared`, `@mdcms/cli`, `@mdcms/sdk`, `@mdcms/studio`, `@mdcms/server`) still clearly maps to its intended responsibility.
126-138: Add a small operational caveat for symlink-based skill discovery (optional).
Rule#7says skills are auto-discovered via symlinks (.claude/skills,.agents/skills,.cursor/skills→../.ai/skills). If symlinks are POSIX-only (or unreliable on some environments like certain Windows setups), it’d be good to explicitly note that here (even one sentence) to reduce setup churn.This is optional if that caveat already exists elsewhere, but I didn’t see it in this section.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@AGENTS.md` around lines 126 - 138, Add a short operational caveat to AGENTS.md under rule `#7`: after the line that lists the symlinks (.claude/skills, .agents/skills, .cursor/skills → ../.ai/skills), add one sentence noting that symlink discovery relies on POSIX-style symlinks and may be unreliable or require admin/dev-mode on some Windows setups (e.g., suggest using junctions or copying the folder as a fallback); reference the existing symbols '.claude/skills', '.agents/skills', '.cursor/skills', and '../.ai/skills' so reviewers can find the exact spot to update..ai/memory/README.md (1)
55-63: Optional: reword repeated “Not a …” bullets to satisfy LanguageTool.
LanguageTool is warning about consecutive sentences starting with “Not a …”. If you want to avoid style gate noise, you can consolidate these into fewer bullets or vary the phrasing slightly (e.g., “This is not used for …”).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.ai/memory/README.md around lines 55 - 63, The "## What this is _not_" section contains several consecutive bullets that all start with "Not a …", triggering LanguageTool style warnings; update that block by consolidating related items into one or two bullets (e.g., combine "Not a status report" and "Not a todo list" into a single "Not used for issue tracking or todo lists") and/or rephrase some bullets (e.g., "This is not a spec" or "Do not use this as a changelog") so the repeated "Not a …" pattern is eliminated while preserving the original exclusions; target the header "## What this is _not_" and its bullet lines when applying the edits.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In @.ai/memory/README.md:
- Around line 55-63: The "## What this is _not_" section contains several
consecutive bullets that all start with "Not a …", triggering LanguageTool style
warnings; update that block by consolidating related items into one or two
bullets (e.g., combine "Not a status report" and "Not a todo list" into a single
"Not used for issue tracking or todo lists") and/or rephrase some bullets (e.g.,
"This is not a spec" or "Do not use this as a changelog") so the repeated "Not a
…" pattern is eliminated while preserving the original exclusions; target the
header "## What this is _not_" and its bullet lines when applying the edits.
In `@AGENTS.md`:
- Around line 205-212: The bulleted list under "Package boundary rules" repeats
the phrase "Keep ..." and triggers style checks; update 1–2 bullets (e.g., the
lines referencing `@mdcms/shared`, `@mdcms/cli`, `@mdcms/sdk`, `@mdcms/studio`,
`@mdcms/server`) to vary phrasing while preserving meaning—replace "Keep" with
alternatives like "Place", "Contain", or "Handle" for some entries and ensure
each package name (e.g., `@mdcms/shared`, `@mdcms/cli`, `@mdcms/sdk`, `@mdcms/studio`,
`@mdcms/server`) still clearly maps to its intended responsibility.
- Around line 126-138: Add a short operational caveat to AGENTS.md under rule
`#7`: after the line that lists the symlinks (.claude/skills, .agents/skills,
.cursor/skills → ../.ai/skills), add one sentence noting that symlink discovery
relies on POSIX-style symlinks and may be unreliable or require admin/dev-mode
on some Windows setups (e.g., suggest using junctions or copying the folder as a
fallback); reference the existing symbols '.claude/skills', '.agents/skills',
'.cursor/skills', and '../.ai/skills' so reviewers can find the exact spot to
update.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: bf63153c-765b-48a1-8287-25a0e627d1b3
📒 Files selected for processing (2)
.ai/memory/README.mdAGENTS.md
- `.ai/memory/README.md` "What this is not" — varied bullet phrasing to drop the repetitive "Not a …" pattern. - `AGENTS.md` package-boundary list — varied verbs (Place / live in / houses / belong / stay) to avoid the repetitive "Keep …" pattern. - `AGENTS.md` rule #7 — added Windows symlink caveat noting that POSIX-style symlinks may not check out cleanly without developer mode or `core.symlinks=true`, with a fallback to junctions or a recursive copy of `.ai/skills/`.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
AGENTS.md (1)
51-52: Consolidate duplicated package-boundary rules to avoid drift.The same ownership rules appear in both “Architecture patterns” and “Package boundary rules.” Consider keeping one canonical section and cross-linking from the other.
Also applies to: 205-214
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@AGENTS.md` around lines 51 - 52, The "Package boundary rules" text is duplicated in the "Architecture patterns" section; remove the redundant copy and keep a single canonical rule set (e.g., retain the wording in "Package boundary rules") and replace the duplicate in "Architecture patterns" with a short cross-reference sentence pointing to the canonical section; update any nearby duplicated instances (the other occurrence around lines 205-214) to also point to the canonical section to prevent future drift and ensure one source of truth.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Around line 73-74: The documentation line for the integration script is
misleading: change the description for "bun run integration" so it reflects all
checks it runs (not just Docker health and migrations). Update the phrase
currently reading "Docker health + migration check" to something like "Docker
health, migration, and content integration checks" (or equivalent wording) so
contributors know the command also runs content integration validation; ensure
"bun run integration" and the word "integration" remain present for
discoverability.
---
Nitpick comments:
In `@AGENTS.md`:
- Around line 51-52: The "Package boundary rules" text is duplicated in the
"Architecture patterns" section; remove the redundant copy and keep a single
canonical rule set (e.g., retain the wording in "Package boundary rules") and
replace the duplicate in "Architecture patterns" with a short cross-reference
sentence pointing to the canonical section; update any nearby duplicated
instances (the other occurrence around lines 205-214) to also point to the
canonical section to prevent future drift and ensure one source of truth.
🪄 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 Plus
Run ID: b0b6b7bf-2bd2-4d41-ba94-85f9ab77b1dc
📒 Files selected for processing (2)
.ai/memory/README.mdAGENTS.md
🚧 Files skipped from review as they are similar to previous changes (1)
- .ai/memory/README.md
Comment on lines
+73
to
+74
| bun run integration # Docker health + migration check | ||
| bun run ci:required # Full CI gate: quality + unit + integration |
There was a problem hiding this comment.
Clarify integration command scope to match actual script behavior.
The description says “Docker health + migration check”, but bun run integration also runs content integration checks. Please expand the wording so contributors don’t underestimate this gate.
Suggested doc patch
-bun run integration # Docker health + migration check
+bun run integration # Docker health + migration check + content integration tests📝 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
| bun run integration # Docker health + migration check | |
| bun run ci:required # Full CI gate: quality + unit + integration | |
| bun run integration # Docker health + migration check + content integration tests | |
| bun run ci:required # Full CI gate: quality + unit + integration |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` around lines 73 - 74, The documentation line for the integration
script is misleading: change the description for "bun run integration" so it
reflects all checks it runs (not just Docker health and migrations). Update the
phrase currently reading "Docker health + migration check" to something like
"Docker health, migration, and content integration checks" (or equivalent
wording) so contributors know the command also runs content integration
validation; ensure "bun run integration" and the word "integration" remain
present for discoverability.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Stand up a team-shared, multi-agent, reproducible-from-fresh-clone AI agent harness in this repo as the pilot for a broader internal initiative. AGENTS.md becomes canonical, vendored superpowers ship in-repo, and Claude Code, Codex, and Cursor all discover the same skill set via symlinks.
What's in this PR
AGENTS.mdcanonicalised,CLAUDE.mdis a@AGENTS.mdshim. Codex, Cursor, Windsurf, VS Code Copilot read AGENTS.md natively; Claude Code via the shim. Old skip-worktree state on AGENTS.md cleared so it's actually committable..ai/directory:LANGUAGE.md— vocabulary (Matt Pocock pattern). Forbids "device flow" since the CLI uses OAuth2 loopback redirect (RFC 8252).plans/— 76 historical plans migrated from local-onlydocs/plans/. Now committed.research/— date-prefixed research artifacts (empty for now,.gitkeep).memory/— team product knowledge:product.md,architecture.md,stack.md,lessons.md, plustopics/,integrations/,initiatives/subdirs. Fivetopics/seed files (auth-flow, push-pull-sync, schema-sync, multi-tenancy, module-system) and threeintegrations/seed files (nx-mcp, docker-stack, github-actions) verified against actual code.skills/— vendoredobra/superpowersv5.0.7 (MIT, Jesse Vincent).LICENSE.superpowerspreserves attribution. Bump procedure documented inskills/README.md. Vendored SKILL.md files patched to write to.ai/plans/and.ai/research/instead of upstream'sdocs/superpowers/(gitignored)..claude/settings.jsondisables the globalsuperpowers@claude-plugins-officialplugin so the vendored copy is authoritative..claude/skills,.agents/skills,.cursor/skills→../.ai/skills. Multi-agent skill discovery without duplication..codex/config.tomlcommitted (project Nx-MCP setup).apps/cli/AGENTS.mdandapps/server/AGENTS.mdupdated to drop "device flow" and corrected on session storage (Postgres, not Redis).docs/specs/SPEC-013-mintlify-docs-site.mdsame vocab fix..gitignoreadds.vercel/,*.tsbuildinfo, personal local-only skill paths,.claude/settings.local.json..prettierignoreexcludes vendored.ai/skills/and historical.ai/plans/so future bumps stay verbatim.Memory bank shape
Initial draft used Cline's 5-file solo template (project-brief / active-context / system-patterns / tech-context / progress). Revised to drop
active-context.mdandprogress.mdbecause they're replace-style writes that conflict on every concurrent PR. Stable knowledge lives in single-purpose files; volatile state stays in Jira /ROADMAP_TASKS.md/ GitHub Issues.Out of scope (deferred)
Listed in roadmap order, not necessarily priority:
/install-dot-ai-style).Known caveats
lessons.mdis a single shared-write file — concurrent appends will need manual merge resolution. Acceptable tradeoff for now; can split per-entry later if it becomes painful.packages/studio/src/lib/runtime-ui/components/ui/button.test.tsxis untracked working-directory state on the author's machine and is not included in this PR. CI sees only what's committed.Test plan
bun run format:checkpassesbun run checkpasses (build + typecheck)superpowers:*entries from global plugin).agents/skills/content.cursor/skills/content/Users/...paths committed (verified bygrep -r '/Users/' .ai/)Summary by CodeRabbit
Documentation
New Features
Chores