docs: Replace vteam references with ACP naming #480
Conversation
- Update all API groups from vteam.ambient-code to acp.ambient-code - Update namespaces from vteam-dev to acp-dev - Update container images from vteam_* to acp_* - Update routes/URLs from vteam-frontend/backend to acp-frontend/backend - Replace 'vTeam' product name with 'Ambient Code Platform' or 'ACP' - Add new Mermaid architecture diagrams to docs/ - Update components/README.md with diagram references Affected areas: - User guides and getting started documentation - GitLab integration documentation (5 files) - Development and testing documentation - Build metadata and deployment docs - Design documents and ADRs - Implementation plans - Reference documentation and API docs - Lab exercises Total: 27 modified files, 4 new diagram files All vteam references removed from platform/docs/
bobbravo2
added
documentation
This comment has been minimized.
This comment has been minimized.
|
looks good, but is the crd planned to be migrated after this name change
|
I think that's wise. Docs first, less risk of breaking infra this way. |
Claude Code ReviewSummaryThis PR successfully renames vTeam references to "Ambient Code Platform" (ACP) across documentation while adding new Mermaid architecture diagrams. The changes are primarily documentation updates with no code modifications, making this a low-risk refactoring. Scope: 31 files changed (27 modified, 4 new diagrams)
Issues by Severity🚫 Blocker IssuesNone - This is a documentation-only PR with no blockers. 🔴 Critical IssuesNone - Documentation changes are straightforward and well-executed. 🟡 Major Issues1. Code Migration Not AddressedLocation: This PR updates docs only, but code still uses Impact: Potential confusion between documentation (ACP) and actual system behavior (vteam). Current State (per CLAUDE.md): Recommendation:
🔵 Minor Issues1. Mermaid Diagram AccessibilityLocation: New diagram files ( Issue: Mermaid diagrams may not render in all contexts (GitHub web, IDEs without plugins). Evidence:
Recommendations:
Example addition: <!--
Plain-text flow: User → Frontend → Backend → Operator → Job → Pod → Results
For best viewing: Use Mermaid preview or render at mermaid.live
-->2. Incomplete URL Updates in Some FilesLocation: Issue: While most Found in PR diff: URLs properly updated from # Before
curl -X POST http://vteam-backend:8080/api/auth/gitlab/connect
# After
curl -X POST http://acp-backend:8080/api/auth/gitlab/connectStatus: ✅ Appears complete, but recommend spot-check during 3. Testing Checklist Partially CompleteLocation: PR description Checklist items: - [ ] Run mkdocs serve and verify all 4 new diagrams render correctly
- [ ] Spot-check 2-3 updated doc pages in browser
- [ ] Verify components/README.md diagram links work
- [ ] Update CLAUDE.md migration status note (or create follow-up issue)
- [ ] Create tracking issue for code migration (or confirm one exists)Recommendation: Complete these before merge to ensure quality. Positive Highlights🌟 Excellent Documentation Structure
🔧 Good Engineering Practices
RecommendationsPriority 1 (Before Merge)
Priority 2 (Post-Merge)
Priority 3 (Future Work)
Compliance Check✅ Follows CLAUDE.md Standards
✅ No Security Issues
✅ Architecture Alignment
Final Verdict✅ APPROVE with minor recommendations This PR successfully achieves its goal of renaming vTeam to Ambient Code Platform in documentation. The new Mermaid diagrams are high-quality additions that improve understanding of the system architecture. Merge Status: Safe to merge after completing testing checklist Post-Merge Actions:
Risk Level: 🟢 LOW - Documentation-only changes with no code impact Review Metadata
🔍 View AI decision process (logs available for 90 days) 📋 View memory system files loaded (click to expand)What Amber Loaded for Code ReviewAmber automatically loaded these repository standards from the memory system:
Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines. |
- Revert API group to vteam.ambient-code (maintain backward compatibility) - Revert namespace to vteam-dev (avoid breaking deployments) - Revert service/route names to vteam-* (maintain service discovery) - Revert container image names to vteam-* in examples - Keep product name changes (vTeam → ACP in narrative text) - Keep new Mermaid architecture diagrams Per ACP Constitution naming guidelines, technical artifacts must remain as 'vteam' for backward compatibility. Only user-facing narrative text uses 'Ambient Code Platform' or 'ACP'. Fixes 24 files with breaking changes while preserving improvements.
bobbravo2
force-pushed
the
docs/replace-vteam-with-acp
branch
from
3ff93ce to
9eb2677
Compare
Claude Code ReviewSummaryThis PR successfully completes the documentation rebranding from "vTeam" to "Ambient Code Platform (ACP)". The changes are documentation-only with no code modifications, making this a low-risk update. The PR adds valuable Mermaid architecture diagrams that significantly enhance documentation quality. Overall Assessment: ✅ Approved with minor recommendations Issues by Severity🚫 Blocker IssuesNone - This is a documentation-only change with no blockers. 🔴 Critical Issues1. Inconsistent vteam references in component-structure.mmd Location: Issue: The diagram still references the old URL pattern: Should be: Impact: This contradicts the PR's stated goal of removing all vteam references from docs/. Users following the diagram will expect the wrong URL. Recommendation: Update line 33 to use 🟡 Major Issues1. CLAUDE.md migration status needs update Location: PR checklist item not addressed Issue: The PR checklist states: This was not completed. CLAUDE.md still references:
Recommendation: After this PR merges, update CLAUDE.md to clarify:
2. Missing tracking issue for code migration Location: PR checklist Issue: Checklist item: Recommendation: Before merging, either:
🔵 Minor Issues1. .gitignore changes unrelated to PR scope Location: Issue: Added security scan artifacts: While not harmful, this is scope creep for a "docs rebranding" PR. This type of change should be in a separate commit for better git history. Recommendation: Either:
2. Diagram accessibility considerations Location: All 4 new .mmd files Issue: Mermaid diagrams use emojis and color-coding for visual clarity, but:
Recommendation (Future enhancement):
Note: This is a nice-to-have improvement, not a blocker. 3. Inconsistent comment style in SECURITY_DEV_MODE.md Location: Before: "vteam-dev", // Legacy local dev namespaceAfter: "vteam-dev", // Local dev namespaceIssue: Removed "Legacy" but code still uses Recommendation: Restore "Legacy" in the comment until the code is actually migrated: "vteam-dev", // Legacy local dev namespace (migrate to acp-dev)Positive Highlights✅ Excellent architecture diagrams - The 4 new Mermaid diagrams ( ✅ Comprehensive coverage - 27 files updated, covering user guides, GitLab integration, development docs, and API references. Very thorough. ✅ Consistent naming convention - Replaced "vTeam" with "Ambient Code Platform" and "ACP" consistently throughout. ✅ No code changes - Low risk: this is purely documentation, no behavior changes. ✅ Clear separation of concerns - Correctly preserves backward compatibility in code (vteam_ prefixes remain) while modernizing docs. ✅ Good diagram organization - Diagrams are colocated in RecommendationsBefore Merge (Critical Path)
After Merge (Follow-up)
Testing ValidationPer the PR checklist, ensure these are completed before merge:
Architecture & Code Quality AssessmentDoes it follow CLAUDE.md patterns? ✅ Yes
Security concerns? ✅ None
Performance impact? ✅ None
Testing coverage? ✅ N/A
Final VerdictRecommendation: ✅ Approve after addressing critical issue #1 This is an excellent documentation improvement that modernizes the project branding. The new Mermaid diagrams are a significant value-add. The only blocking issue is the inconsistent URL in Once the vteam URL is fixed and the migration tracking issue is created/linked, this PR is ready to merge. Great work on the thorough rebranding effort! 🎉 |
Claude Code ReviewSummaryThis PR performs a documentation rename from "vTeam" to "Ambient Code Platform (ACP)" and adds new Mermaid architecture diagrams. While the overall intent is good and most changes are correct, there are BLOCKER ISSUES that must be fixed before merge. Overall Assessment: Documentation-only changes with good architecture diagrams, but incomplete migration and accidental inclusion of security scan artifacts. Issues by Severity🚫 Blocker Issues1. Security Scan Artifacts Accidentally CommittedLocation:
Impact:
Fix Required: # Remove from PR
git rm -r .security-scan/ .security-scan.zip
git commit -m "Remove accidentally committed security scan artifacts"
# Add to .gitignore
echo ".security-scan/" >> .gitignore
echo ".security-scan.zip" >> .gitignore
git commit -m "gitignore: Add .security-scan artifacts"2. Incomplete Migration - Old "vteam" References Still PresentLocations:
Impact:
Fix Required: Update all 4 locations above to use correct ACP naming. 🔴 Critical IssuesNone identified (after blockers are fixed). 🟡 Major Issues1. PR Testing Checklist Not CompletedLocation: PR description - [ ] Run `mkdocs serve` and verify all 4 new diagrams render correctly
- [ ] Spot-check 2-3 updated doc pages in browser
- [ ] Verify `components/README.md` diagram links work
- [ ] Update CLAUDE.md migration status note (or create follow-up issue)
- [ ] Create tracking issue for code migration (or confirm one exists)Recommendation:
2. Code Migration Tracking NeededIssue: This PR only updates documentation (
From CLAUDE.md (lines 9, 333, 335): > **Note:** This project was formerly known as "vTeam". Technical artifacts (image names,
> namespaces, API groups) still use "vteam" for backward compatibility.
- **Default namespace**: `ambient-code` (production), `vteam-dev` (local dev)
- **CRD group**: `vteam.ambient-code`Recommendation:
🔵 Minor Issues1. Mermaid Diagram Quality - Good AdditionPositive: The new architecture diagrams are well-structured:
Minor suggestion: Consider adding a diagram index page ( 2. Documentation Scope AppropriatePositive: The PR correctly limits scope to documentation:
Positive Highlights✅ Comprehensive Documentation Coverage: Updated 27 files across all doc categories (user guides, API docs, testing, GitLab integration, ADRs, labs) ✅ Architecture Diagrams Added: Four new Mermaid diagrams provide excellent visual documentation of:
✅ Consistent Naming Pattern: Most replacements follow a clear pattern:
✅ GitLab Integration Docs Updated: All 5 GitLab documentation files updated consistently ✅ Follows Project Standards:
RecommendationsPriority 1 (Must Fix Before Merge)
Priority 2 (Should Do)
Priority 3 (Nice to Have)
Validation ChecklistBased on loaded memory system files: Documentation Standards (CLAUDE.md:1070-1075):
Security Standards:
Project Structure:
Decision: ❌ Do not merge until blocker issues are fixed. After fixes, this will be a valuable documentation update that aligns naming with the project's Ambient Code Platform branding while adding helpful architecture diagrams. 🔍 View AI decision process (logs available for 90 days) 📋 View memory system files loaded (click to expand)What Amber Loaded for Code ReviewAmber automatically loaded these repository standards from the memory system:
Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines. |
- Fix incorrect URL: github.com/natifridman/Ambient Code Platform/issues → https://github.com/ambient-code/platform/issues - Replace placeholder: github.com/your-org/platform → https://github.com/ambient-code/platform Updated files: - docs/gitlab-self-hosted.md (incorrect org/repo name) - docs/user-guide/working-with-amber.md (placeholder URLs)
bobbravo2
left a comment
bobbravo2
left a comment
There was a problem hiding this comment.
✅ Fixed all infra breaking changes:
Reverted acp.ambient-code → vteam.ambient-code (API group)
Reverted acp-dev → vteam-dev (namespace)
Reverted acp-backend, acp-frontend, acp-operator → vteam-* (services/routes)
Reverted container image names in examples
✅ Kept the good changes:
Product name updates (vTeam → Ambient Code Platform/ACP in narrative text)
New Mermaid architecture diagrams (4 new diagram files)
Claude Code ReviewSummaryThis PR successfully migrates documentation from 'vteam' to 'ACP' (Ambient Code Platform) naming and adds valuable Mermaid architecture diagrams. The changes are documentation-only with no code modifications, making this a low-risk, high-value update that improves project clarity and professionalism. Overall Assessment: ✅ Approved with minor recommendations Issues by Severity🚫 Blocker IssuesNone - This PR is safe to merge. 🔴 Critical IssuesNone - All changes are documentation-only with no security, functionality, or architecture concerns. 🟡 Major Issues1. Inconsistent URL in component-structure.mmdLocation: Issue: This diagram still references Expected: Impact: Misleads users about actual development URL pattern. Recommendation: Update to 2. Incomplete migration check neededLocation: PR body mentions "Update CLAUDE.md migration status note" but CLAUDE.md wasn't modified in this PR. Issue: CLAUDE.md still contains references to "vteam" technical artifacts as "legacy" naming, but doesn't mention this documentation migration or when code migration is expected. Current state in CLAUDE.md (line 9): > **Note:** This project was formerly known as "vTeam". Technical artifacts (image names, namespaces, API groups) still use "vteam" for backward compatibility.Recommendation: Either:
🔵 Minor Issues1. .gitignore additions seem unrelatedLocation: Issue: These security scan entries appear unrelated to the vteam→ACP migration. While not harmful, they should ideally be in a separate commit/PR for cleaner git history. Recommendation: Consider moving to a separate PR, or document why they're included here. 2. SECURITY_DEV_MODE.md comment inconsistencyLocation: Before: "vteam-dev", // Legacy local dev namespaceAfter: "vteam-dev", // Local dev namespaceIssue: Removed "Legacy" but the actual namespace name is still Recommendation: Either:
Positive Highlights🌟 Excellent Documentation Enhancements
📊 Quality Metrics
RecommendationsPriority 1: Fix Before Merge
Priority 2: Consider for Follow-up
Priority 3: Enhancement Opportunities
Security Assessment✅ No security concerns
Testing Checklist ValidationYour PR checklist mentions:
Recommendation: Complete items 4-5 before merge, rest can be done during final review. Final VerdictStatus: ✅ APPROVED (with minor fixes recommended) This is excellent work that significantly improves documentation quality and consistency. The Mermaid diagrams are production-ready and will be invaluable for new developers and stakeholders. Merge Readiness: 95%
Impact: High positive impact on developer experience and project professionalism with minimal risk. Great job! 🎉 Reviewed by Claude Code (Sonnet 4.5) using project memory system and security standards 🔍 View AI decision process (logs available for 90 days) 📋 View memory system files loaded (click to expand)What Amber Loaded for Code ReviewAmber automatically loaded these repository standards from the memory system:
Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines. |
Add note that routes also use 'vteam' naming and that documentation uses ACP naming. This clarifies the distinction between technical artifacts (which remain vteam) and user-facing documentation.
Claude Code ReviewSummaryThis PR successfully migrates documentation from "vTeam" branding to "Ambient Code Platform" (ACP) naming conventions and adds valuable Mermaid architecture diagrams. The changes are documentation-only with no code modifications, making this a low-risk update. The documentation updates are consistent, comprehensive, and well-executed. Overall Assessment: ✅ Approved with Minor Recommendations The PR is ready to merge after addressing the pre-merge checklist items. All changes follow documentation standards and maintain consistency with the project's transition strategy. Issues by Severity🚫 Blocker IssuesNone - This is a documentation-only PR with no blockers. 🔴 Critical IssuesNone - All critical documentation patterns are followed correctly. 🟡 Major Issues1. Incomplete Migration TrackingLocation: Current: > **Note:** This project was formerly known as "vTeam". Technical artifacts (image names, namespaces, API groups, routes) still use "vteam" for backward compatibility. The docs use ACP naming.Recommendation: > **Note:** This project was formerly known as "vTeam". Technical artifacts (image names, namespaces, API groups, routes) still use "vteam" for backward compatibility. The docs use ACP naming. See [Issue #XXX] for code migration tracking.2. Mixed URL References in DocumentationLocation: Multiple files (e.g., Examples:
Recommendation: This is correct per the backward compatibility note, but consider adding a prominent callout in affected docs: > **Note**: API endpoints and routes still use `vteam-*` naming for backward compatibility. Future releases will migrate to `acp-*` naming.🔵 Minor Issues1. .gitignore Security Scan ArtifactsLocation: Recommendation: Consider:
2. Diagram File Naming ConventionLocation: Recommendation: Verify this aligns with the documentation standards in 3. Diagram ComplexityLocation: Recommendation:
Positive Highlights✅ Excellent Documentation Quality
✅ Well-Structured Changes
✅ Diagram Excellence
RecommendationsPre-Merge Checklist ComplianceEnsure the PR checklist items are completed:
Documentation TestingSince this is a docs-only PR, recommend:
Follow-Up WorkConsider creating issues for:
Alignment with Project Standards✅ Follows CLAUDE.md GuidelinesPer
Assessment: The PR correctly:
✅ No Security Concerns
✅ No Performance Impact
Final RecommendationApprove and merge after completing the pre-merge checklist. Suggested merge order:
Post-merge:
Reviewed by: Claude Code (Sonnet 4.5) 🔍 View AI decision process (logs available for 90 days) 📋 View memory system files loaded (click to expand)What Amber Loaded for Code ReviewAmber automatically loaded these repository standards from the memory system:
Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines. |
3 participants
Testing before merge checklist
Before merge:
mkdocs serveand verify all 4 new diagrams render correctlycomponents/README.mddiagram links workChange summary
Affected areas:
Total: 27 modified files, 4 new diagram files
All vteam references removed from platform/docs/