Skip to content

Documentation Inconsistencies

This document tracks inconsistencies and misalignments between the AI Factory documentation and the company documentation. It serves as a reference for identifying areas that need alignment, content gaps, and solution misalignments.

Note

This document is maintained as a living reference. Items are removed as inconsistencies are resolved.

Recent Resolutions

Vision and Strategy Alignment (Completed): - Strategic Goals document enhanced with Core Concepts, Strategic Themes, Time Horizons, and Business Strategy alignment - Vision Overview document enhanced with Factory's role in ConnectSoft ecosystem and Strategic Moat sections - Why AI Software Factory document aligned with company documentation version - Terminology consistency verified (Core Platform, SaaS Cycles, 4 Pillars) - All timelines verified to start from January 1, 2026 - Technology stack references updated (.NET 10+, Microsoft.Extensions.AI, Agent Framework)

Final-State Architecture Alignment (twelve-platform model)

The final-state architecture documentation set (ai-software-factory/, platforms/, architecture/, catalogs/, reference/) is now the primary, authoritative description of the target system. Existing implementation docs have been re-homed under the Implementation nav tab and linked from the final-state docs. The following items were found during the alignment pass and are flagged for an incremental cleanup; the canonical choice is already stated in the final-state docs (Architecture Principles, Glossary).

Finding Canonical (final-state) Legacy occurrences Action
Agent runtime Microsoft Agent Framework (Microsoft.Agents.AI.*) + Microsoft.Extensions.AI Residual Semantic Kernel / SK terminology in legacy spec pages ✅ RESOLVED — bulk-normalized to Agent Framework, Microsoft.Extensions.AI, and MCP across agents/, platform-architecture/, templates-docs/, and related pages. ADR-0002 retains Semantic Kernel only as the rejected alternative.
IaC tool Pulumi (.NET/C#) "Bicep" appears in platform-architecture/*, core-principles/cloud-native-mindset.md, agent specs, factory/runtime/control-plane.md Reframe Bicep as legacy alternative only; new IaC is Pulumi. Final-state DevOps docs already do this.
Knowledge naming Knowledge Platform (alias: "Knowledge Fabric") "Knowledge Fabric" / "Knowledge and Memory System" in platform-architecture/* Alias recorded in glossary; hub pages now link to the Knowledge Platform.
Backend version .NET 10+ residual ".NET 8/9" in some specs ✅ RESOLVED — normalized to .NET 10+ across documentation.
gRPC contracts Code-first C# (ServiceModel.Grpc, no .proto) Proto/protobuf as default for internal gRPC ✅ RESOLVED — internal gRPC documented as code-first; .proto reserved for foreign-stack anti-corruption adapters only.

Note

Bicep and a few foreign-stack .proto references remain where they describe legacy or non-ConnectSoft integrations. The authoritative final-state stack is defined in AI Software Factory Glossary and Architecture Principles.

Terminology and Naming

Inconsistencies

AI Factory Docs Company Docs Issue Resolution Needed
"AI Factory" "AI Software Factory" Inconsistent naming Standardize on "AI Software Factory"
"Factory" "AI Software Factory" Abbreviation usage varies Define when abbreviation is acceptable
"Blueprint" "Blueprint" Generally consistent No action needed
"Agent" "AI Agent" Sometimes inconsistent Standardize on "Agent" or "AI Agent" consistently
"Semantic Kernel" "Microsoft Agent Framework" / "Microsoft.Extensions.AI" Technology stack terminology ✅ RESOLVED - Replaced across agent specs, platform architecture, and template docs
".NET 8/9" ".NET 10+" Version references ✅ RESOLVED - Updated to .NET 10+ throughout documentation
"Core Platform" "Core Platform" Terminology consistency ✅ RESOLVED - Now consistently used across vision documents
"SaaS Cycles" "SaaS Cycles (1-5)" Terminology consistency ✅ RESOLVED - Now consistently referenced in strategic goals
"4 Pillars" / "Four Pillars" "Four Product Pillars" Terminology consistency ✅ RESOLVED - Now consistently referenced in vision documents

Architecture and Design

Template Architecture

Issue: AI Factory docs reference template architecture from starters documentation, but some details may not align with company documentation.

Location: - AI Factory: templates-docs/template-architecture.md - Company: ConnectSoft.Documentation/Docs/starters/template-architecture-specification.md

Status: ✅ RESOLVED - All extended templates have been aligned to the three-layer DI model using MicroserviceRegistrationBase hooks. templates-overview.md now includes a DI alignment status section. The base-template-di-extensibility.md docs in both public and company repos have been updated with the extended template registration classes, override strategies, Program.cs Serilog bootstrap pattern, and migration checklist.

Platform Architecture

Issue: Company documentation may have different emphasis on certain architectural patterns.

Location: - AI Factory: platform-architecture/overall-architecture.md - Company: Various architecture documents

Status: Needs review

Roadmap and Timeline Alignment

Timeline Start Dates

Issue: All roadmaps should start from January 1, 2026.

Status: ✅ RESOLVED - All roadmap documents and strategic goals now start from January 1, 2026. Time horizons in strategic-goals.md are properly aligned with company documentation.

Roadmap Phases

Issue: Company documentation may have different phase definitions or timelines.

Location: - AI Factory: roadmap/short-term-plan.md, roadmap/mid-term-expansion.md, roadmap/long-term-platform-evolution.md - Company: roadmaps/factory-roadmap.md

Status: Needs review for alignment

Agent Specifications

Agent Naming and Roles

Issue: Some agent names or roles may differ between AI Factory docs and company docs.

Location: - AI Factory: agents/detailed-agent-specifications/*.md - Company: Various agent references

Status: Needs review

Database Architect Naming Gap

Issue: Company documentation referenced a "Database Architect" role but no corresponding agent existed in the AI Factory agent registry. The role was ambiguous between architecture-level database design and hands-on database engineering.

Status: ✅ RESOLVED - The Database Engineer Agent has been added to the Software Engineering cluster. This agent covers schema design, migration scripts, and database optimization — aligning the AI Factory agent registry with the company documentation's intent for database-focused automation.

Incubator Agent Registry Gap

Issue: Several agent concepts referenced across planning documents and incubator discussions were not registered in the agent cluster tables, mesh topology, or system component documentation. This created a gap between planned agent capabilities and documented architecture.

Status: ✅ RESOLVED - 27 new agents have been added across all platform architecture documentation (agentic-system-design.md, system-components.md). New clusters added: UX/UI, Security, Observability, Documentation, Growth, and Platform Evolution. All agents are now registered in cluster tables, execution group listings, and mesh topology diagrams.

Agent Capabilities

Issue: Agent capabilities and skills may be described differently.

Status: Needs review

Template Documentation

Template Availability

Issue: AI Factory docs may reference templates that don't exist or have different names in company docs.

Location: - AI Factory: templates-docs/*.md - Company: ConnectSoft.Documentation/Docs/starters/*

Status: Needs review

Template Parameters

Issue: Template parameters may differ between documentation sets.

Status: Needs review

Workflow Documentation

Workflow Definitions

Issue: Workflow definitions may differ between AI Factory and company documentation.

Location: - AI Factory: workflows/*.md - Company: Various workflow references

Status: Needs review

Vision and Strategy

Strategic Goals

Issue: Strategic goals may be worded differently or have different emphasis.

Location: - AI Factory: vision/strategic-goals.md - Company: factory/strategic-goals.md

Status: ✅ RESOLVED - Strategic goals document has been enhanced with: - Core Concepts section (Core Platform, Templates, SaaS Cycles) - Strategic Themes section mapping 10 goals to 4 themes - Time Horizons section (Short/Mid/Long term starting January 2026) - Alignment with Business Strategy section - OKR-style key results - Enhanced introduction explaining Factory's role in ConnectSoft strategy

Vision Statements

Issue: Vision statements may have different wording or emphasis.

Location: - AI Factory: vision/vision-overview.md - Company: Various vision documents

Status: ✅ RESOLVED - Vision overview document has been enhanced with: - Factory's role in ConnectSoft's 4-pillar portfolio section - "Factory in the ConnectSoft Ecosystem" section - Strategic Moat section explaining knowledge system and accumulated assets - Factory's role in 5-cycle strategy section - Enhanced "What Makes It AI-Driven?" section aligned with company vision

Platform Foundations

MCP Servers

Issue: MCP server documentation may have different details or emphasis.

Location: - AI Factory: archive/connectsoft-mcp-servers-catalog.md - Company: Various MCP references

Status: Needs review

Content Gaps

Missing Documentation

Issue: Some topics covered in company documentation may be missing from AI Factory docs.

Areas to Review: - Business model details - Pricing and licensing - Partner program - Customer onboarding process - Support processes

Status: Needs review

Incomplete Documentation

Issue: Some AI Factory docs may be incomplete compared to company documentation.

Areas to Review: - Template architecture details - Agent implementation specifics - Workflow execution details - Studio features

Status: Needs review

Solution Misalignments

Technical Approach

Issue: Technical approaches may differ between documentation sets.

Areas to Review: - Template composition approach - Agent execution model - Orchestration patterns - Observability implementation

Status: Needs review

Implementation Details

Issue: Implementation details may differ or be missing.

Areas to Review: - Runtime architecture - State management - Failure handling - Recovery mechanisms

Status: Needs review

Recommendations

Priority Actions

  1. High Priority:
  2. ✅ Align terminology and naming conventions (Partially resolved - Core Platform, SaaS Cycles, 4 Pillars now consistent)
  3. ✅ Review and align roadmap timelines and phases (Resolved - All timelines start from January 1, 2026)

  4. Verify template architecture alignment

  5. Medium Priority:

  6. Review agent specifications for consistency
  7. Align workflow definitions

  8. ✅ Verify vision and strategy alignment (Resolved - Strategic goals and vision documents aligned)

  9. Low Priority:

  10. Fill content gaps
  11. Complete incomplete documentation
  12. Review solution misalignments

Review Process

  1. Identify Inconsistencies: Use this document as a starting point
  2. Verify Against Source: Check company documentation for authoritative source
  3. Update AI Factory Docs: Align AI Factory documentation with company documentation
  4. Mark as Resolved: Update this document when inconsistencies are resolved