quality-debt: README.md — PR #2650 review feedback (medium)

[marcusquinn]

Unactioned Review Feedback

Source PR: #2650
File: README.md
Reviewers: gemini
Findings: 2
Max severity: medium

---

MEDIUM: gemini (gemini-code-assist[bot])

File: README.md:499

For clarity and consistency with other entries in this table that mention specific scripts, consider making this more specific. The "memory system" is implemented via memory-helper.sh. This aligns with the guideline to restore key helper scripts to domain index entries for clarity, especially if they are frequently used.

| **Pattern Tracking** | Learn what works/fails | `/patterns` command, `memory-helper.sh` |

References

1. For clarity in documentation, restore key helper scripts and commands to domain index entries if they are frequently used, even if detailed documentation exists elsewhere.

View comment

MEDIUM: gemini (gemini-code-assist[bot])

File: README.md:632

For clarity and consistency, consider mentioning the specific script that implements this, similar to how other parts of the documentation refer to helper scripts. The "memory system" for this purpose is primarily accessed via memory-helper.sh. This aligns with the guideline to restore key helper scripts to domain index entries for clarity, especially if they are frequently used.

| **Review** | Analyze memory for success/failure patterns (`memory-helper.sh`) |

References

1. For clarity in documentation, restore key helper scripts and commands to domain index entries if they are frequently used, even if detailed documentation exists elsewhere.

View comment

---

Auto-generated by quality-feedback-helper.sh scan-merged. Review each finding and either fix the code or dismiss with a reason.

[marcusquinn]

Additional Review Feedback (PR #215)

Reviewers: gemini
Findings: 1
Max severity: medium

---

MEDIUM: gemini (gemini-code-assist[bot])

File: README.md:1432

For improved clarity and technical accuracy, it's better to use the full term apple-touch-icon instead of the abbreviated apple-touch. This ensures the documentation is precise and unambiguous for developers.

| `@debug-favicon` | Validate favicon setup across platforms (ico, apple-touch-icon, manifest) |

View comment

---

Appended by quality-feedback-helper.sh scan-merged (cross-PR file dedup, t1411).

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[marcusquinn]

Additional Review Feedback (PR #229)

Reviewers: gemini
Findings: 1
Max severity: medium

---

MEDIUM: gemini (gemini-code-assist[bot])

File: README.md:94

This line states there are '15 primary agents', but with the removal of Plan+ (a primary agent) and the clarification that @plan-plus is a subagent, this count is no longer accurate for primary agents. The table on line 1239 lists 15 agents in total, including @plan-plus. To improve clarity and avoid confusion for users, I suggest removing the specific count from this summary line.

- Primary agents (Build+, SEO, Marketing, etc.) with @plan-plus subagent for planning-only mode

View comment

---

Appended by quality-feedback-helper.sh scan-merged (cross-PR file dedup, t1411).

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[marcusquinn]

Additional Review Feedback (PR #403)

Reviewers: coderabbit, human
Findings: 5
Max severity: high

---

MEDIUM: coderabbit (coderabbitai[bot])

File: README.md:721
⚠️ Potential issue | 🟡 Minor

Trim the Voice section to progressive disclosure.

This block re-implements the full how‑to; per guidelines, README should summarize and point to the subagent doc with file:line references.

✂️ Suggested condensation

-Open-source speech-to-speech pipeline based on [huggingface/speech-to-speech]...
-...
-**See:** [speech-to-speech.md](.agents/tools/voice/speech-to-speech.md) for full component options, CLI parameters, and integration patterns (Twilio phone, video narration, voice-driven DevOps).
+Open-source speech-to-speech pipeline (VAD → STT → LLM → TTS) for local and cloud GPU.
+See `file:.agents/tools/voice/speech-to-speech.md` for setup, presets, and integration patterns.

🤖 Prompt for AI Agents

In `@README.md` around lines 665 - 721, Condense the "Voice Integration" section:
replace the long Quick start, full CLI examples, and exhaustive hardware/method
tables with a short summary paragraph and a single compact "Getting started"
one-liner that mentions speech-to-speech-helper.sh; fold the detailed setup
steps, presets, hardware recommendations, and extra methods into a pointer to
the subagent doc (speech-to-speech.md) and include a file:line reference there;
keep one small expandable details/blockquote if needed for progressive
disclosure but remove duplicated how-to content from README.md.

View comment

HIGH: coderabbit (coderabbitai[bot])

File: README.md:697
⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Locate and verify README.md
fd -t f "README.md" -x wc -l {}

Repository: marcusquinn/aidevops

Length of output: 5027

---

🏁 Script executed:

#!/bin/bash
# Check lines 687-697 in README.md
if [ -f "README.md" ]; then
  echo "=== Lines 687-697 ===" 
  sed -n '687,697p' README.md
  echo ""
  echo "=== Context (680-705) ===" 
  sed -n '680,705p' README.md
fi

Repository: marcusquinn/aidevops

Length of output: 1775

---

🏁 Script executed:

#!/bin/bash
# Search for other hardcoded IPs or API examples in README.md
if [ -f "README.md" ]; then
  echo "=== Searching for IP addresses and API examples ===" 
  rg -n "(--host|--llm|open_api|API|api)" README.md | head -20
fi

Repository: marcusquinn/aidevops

Length of output: 2061

---

🏁 Script executed:

#!/bin/bash
# Check for .env or secret storage mentions in documentation
rg -l "api|secret|key|credential" --type md | head -10

Repository: marcusquinn/aidevops

Length of output: 334

---

🏁 Script executed:

#!/bin/bash
# Check for other potential hardcoded examples in README
echo "=== Searching for other potential hardcoded values or API examples ===" 
rg -n "(192\.|10\.|172\.|localhost|OPENAI|api_key|API_KEY|secret|token)" README.md | grep -v "^[0-9]*:.*#.*comment"

Repository: marcusquinn/aidevops

Length of output: 3693

---

🏁 Script executed:

#!/bin/bash
# Check what's around those config presets to see if any mention API credentials
sed -n '688,705p' README.md | cat -n

Repository: marcusquinn/aidevops

Length of output: 1078

---

🏁 Script executed:

#!/bin/bash
# Search for examples of how other commands/presets mention API or credentials
rg -B2 -A2 "(OpenAI|api|credential|key|token)" README.md | head -40

Repository: marcusquinn/aidevops

Length of output: 2418

---

Replace hardcoded IP with placeholder and add secure key storage guidance.

The example hardcodes 192.168.1.100 and the low-latency preset mentions OpenAI API without guidance on secure credential storage. Replace the IP with a placeholder and add a note directing users to ~/.config/aidevops/mcp-env.sh (600 permissions) for cloud API keys.

✏️ Suggested edit

-speech-to-speech-helper.sh client --host 192.168.1.100
+speech-to-speech-helper.sh client --host <server-ip>
+
+# If using cloud APIs (e.g., `low-latency` preset with OpenAI), store keys in
+# ~/.config/aidevops/mcp-env.sh (600 perms) or a gitignored .env file.

📝 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.

# Server mode (clients connect remotely)
speech-to-speech-helper.sh start --server
speech-to-speech-helper.sh client --host <server-ip>

# If using cloud APIs (e.g., `low-latency` preset with OpenAI), store keys in
# ~/.config/aidevops/mcp-env.sh (600 perms) or a gitignored .env file.

# Configuration presets
speech-to-speech-helper.sh config low-latency   # Fastest (CUDA + OpenAI API)
speech-to-speech-helper.sh config low-vram       # Minimal GPU (~4GB)
speech-to-speech-helper.sh config quality        # Best quality (24GB+ VRAM)
speech-to-speech-helper.sh config mac            # Apple Silicon optimal
speech-to-speech-helper.sh config multilingual   # Auto language detection (6 langs)

🤖 Prompt for AI Agents

In `@README.md` around lines 687 - 697, Replace the hardcoded IP in the client
example (speech-to-speech-helper.sh client --host 192.168.1.100) with a
placeholder like <SERVER_IP>, and update the "low-latency" preset description to
include a short note about secure API credential storage for OpenAI (or cloud
APIs) by pointing users to store keys in ~/.config/aidevops/mcp-env.sh with
strict permissions (chmod 600). Ensure the README text references the client
invocation (speech-to-speech-helper.sh client --host <SERVER_IP>) and the
credential file path and permissions in the same section so users know where and
how to securely store their API keys.

✅ Confirmed as addressed by @marcusquinn

View comment

MEDIUM: human (marcusquinn)

File: README.md:697
Valid. Fixed: Replaced 192.168.1.100 with placeholder in the helper script help text. The README already uses in the current version.

View comment

MEDIUM: coderabbit (coderabbitai[bot])

File: README.md:721
@marcusquinn, understood. I acknowledge your decision to keep the Voice section at its current level of detail. You've balanced providing enough context for users to get started quickly while still pointing to the comprehensive documentation in speech-to-speech.md for the full details.

---

🧠 Learnings used

Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-17T02:07:48.870Z
Learning: Applies to **/AGENTS.md : Use progressive disclosure in AGENTS.md with pointers to subagents rather than inline content

---

Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Reference AGENTS.md for authoritative AI assistant guidance instead of GEMINI.md

---

Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Reference AGENTS.md (authoritative) instead of AGENT.md for AI assistant guidance

---

Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-07T02:15:53.636Z
Learning: Applies to .agents/AGENTS.md : Organize agent documentation with instructions budget of ~50-100 max in root AGENTS.md, using progressive disclosure with pointers to subagents

---

Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-17T02:07:48.870Z
Learning: Applies to **/AGENTS.md : Limit root AGENTS.md to ~50-100 max instructions with universal applicability to >80% of tasks

---

Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-07T02:15:53.636Z
Learning: Applies to .agents/AGENTS.md : Keep every instruction in root AGENTS.md relevant to >80% of tasks

---

Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Maintain all AI assistant instructions, documentation, and operational guidance in AGENTS.md as the single source of truth

View comment

MEDIUM: coderabbit (coderabbitai[bot])

File: README.md:697
@marcusquinn, thanks for addressing this! Replacing the hardcoded IP with <server-ip> in the helper script's help text is the right approach for security documentation. Using placeholders prevents copy-paste mistakes that could expose internal network topology.

The credential storage guidance (pointing to ~/.config/aidevops/mcp-env.sh with 600 permissions) also aligns with the existing learning about storing API keys securely in ~/.config/aidevops/credentials.sh.

🐰✨

---

🧠 Learnings used

Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: templates/home/AGENTS.md:0-0
Timestamp: 2026-02-06T22:44:23.940Z
Learning: Applies to templates/home/**/*.{sh,bash,zsh} : Store API keys and tokens in ~/.config/aidevops/credentials.sh with file permissions set to 600 (owner read/write only), never store credentials in ~/.aidevops/.agent-workspace/, Git repositories, home directory root, or hardcoded in code

---

If you found this review helpful, would you consider giving us a shout-out on X?

Thank you for using CodeRabbit!

View comment

---

Appended by quality-feedback-helper.sh scan-merged (cross-PR file dedup, t1411).

[marcusquinn]

Additional Review Feedback (PR #87)

Reviewers: gemini
Findings: 2
Max severity: medium

---

MEDIUM: gemini (gemini-code-assist[bot])

File: README.md:111

While combining brew tap and brew install is a great simplification, adding && aidevops update is redundant. The Homebrew formula's post_install hook already takes care of deploying the agents by running setup.sh. The command should just be brew install marcusquinn/tap/aidevops.

brew install marcusquinn/tap/aidevops

View comment

MEDIUM: gemini (gemini-code-assist[bot])

File: README.md:1478

Similar to the other Homebrew command in this file, the && aidevops update part is redundant because the formula's post_install hook already handles agent deployment. The command can be simplified.

brew install marcusquinn/tap/aidevops

View comment

---

Appended by quality-feedback-helper.sh scan-merged (cross-PR file dedup, t1411).

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[marcusquinn]

Additional Review Feedback (PR #777)

Reviewers: gemini
Findings: 1
Max severity: medium

---

MEDIUM: gemini (gemini-code-assist[bot])

File: README.md:1485

This documentation for the Research agent's model tier should be consistent with the definition in .agents/subagent-index.toon. As gemini/grok is likely an incorrect tier name, this line should be updated once the configuration is corrected to maintain documentation accuracy.

| Research | `research.md` | Research and analysis tasks | grok |

View comment

---

Appended by quality-feedback-helper.sh scan-merged (cross-PR file dedup, t1411).

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[marcusquinn]

Additional Review Feedback (PR #420)

Reviewers: gemini
Findings: 1
Max severity: medium

---

MEDIUM: gemini (gemini-code-assist[bot])

File: README.md:74

The MCP server count in the badge is updated to 17, and the section header at line 890 is also updated to '17 active'. However, after removing Outscraper, the list of supported MCPs from line 896 to 913 contains 18 entries. This seems to be a discrepancy. Could you please verify the count and update either the badge/header or the table to be consistent?

View comment

---

Appended by quality-feedback-helper.sh scan-merged (cross-PR file dedup, t1411).

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[marcusquinn]

Additional Review Feedback (PR #395)

Reviewers: gemini
Findings: 2
Max severity: medium

---

MEDIUM: gemini (gemini-code-assist[bot])

File: README.md:444

For better readability and consistency with other items in this list, consider rephrasing this long line. It currently mixes specific tool names with general capabilities, which makes it harder to parse than other list items. Separating these concerns would improve clarity.

- **SEO Toolchain**: 13 SEO subagents for technical analysis, programmatic SEO, and analytics, integrating with tools like Semrush, Ahrefs, ContentKing, and Screaming Frog.

View comment

MEDIUM: gemini (gemini-code-assist[bot])

File: README.md:1694

The description for the /runners command here is less detailed than the one provided earlier in the 'Autonomous Orchestration' section (line 430). To maintain consistency and provide fuller information in this command reference table, consider using the more descriptive version here as well.

| `/runners` | Batch dispatch from task IDs, PR URLs, or descriptions with concurrency control and progress monitoring |

View comment

---

Appended by quality-feedback-helper.sh scan-merged (cross-PR file dedup, t1411).

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!