bc-code-intelligence-mcp 1.4.4 → 1.5.0

package/embedded-knowledge/domains/alex-architect/delegating-to-github-copilot-agents.md

@@ -0,0 +1,371 @@
+---
+title: "Delegating Coding Tasks to GitHub Copilot Agents"
+domain: "alex-architect"
+bc_versions: "14+"
+difficulty: "intermediate"
+tags: ["ai-workflow", "delegation", "github-copilot", "issue-creation", "context-management"]
+related_topics:
+  - "../shared/naming-conventions.md"
+  - "../shared/object-numbering.md"
+  - "../../specialists/alex-architect.md"
+applies_to:
+  - "GitHub Copilot Agents"
+  - "Issue Management"
+  - "AI-Assisted Development"
+last_updated: "2025-10-26"
+---
+
+# Delegating Coding Tasks to GitHub Copilot Agents
+
+## Overview
+GitHub Copilot Agents can execute coding tasks autonomously when assigned to Issues, but they operate with **limited context**—only what's in the Issue description and repository code. As an architect, your role is to craft Issues that provide sufficient context for Copilot Agents to implement BC solutions correctly, following your organization's standards.
+
+**Key Challenge**: Unlike interactive Copilot sessions, Agents can't ask clarifying questions. All context must be front-loaded in the Issue.
+
+## Essential Context for BC Coding Tasks
+
+### 1. Object Identity & Numbering
+Always specify exact object details to avoid ambiguity:
+
+```markdown
+## Object Details
+- **Table**: `MyTable` (Table 50100)
+- **Page**: `MyTable Card` (Page 50101)
+- **Codeunit**: `MyTable Management` (Codeunit 50100)
+- **Field to Add**: `Priority Code` (Field 50010, Code[20])
+```
+
+**Why This Matters**: BC has strict object ID requirements. Without this, Copilot Agent might:
+- Use incorrect object IDs (causing conflicts)
+- Create objects with wrong types
+- Miss relationships between objects
+
+### 2. Naming Conventions (Critical!)
+Include your organization's naming standards, especially from loaded BC Code Intel layers:
+
+```markdown
+## Naming Conventions
+Following [Company Name] standards from company knowledge layer:
+
+- **Prefixes**: All custom objects use `ABC_` prefix
+- **Field Naming**: `ABC Description` not `ABCDescription` (space-separated)
+- **Codeunit Methods**: PascalCase with verb-noun pattern (`CalculateTotalAmount`, not `CalcTotal`)
+- **Variables**: Descriptive names, avoid abbreviations (`CustomerLedgerEntry`, not `CustLE`)
+- **Boolean Fields**: Start with `Is`, `Has`, or `Can` (`IsBlocked`, `HasShipmentAddress`)
+```
+
+**Pro Tip**: Reference your company's BC Code Intelligence layer explicitly:
+```markdown
+See company layer: `domains/naming-conventions/field-naming-standards.md`
+```
+
+### 3. Business Central Context
+Provide BC-specific architectural context:
+
+```markdown
+## BC Architecture Context
+- **Pattern**: Follow standard BC document pattern (Header-Line structure)
+- **Events**: Subscribe to `OnAfterInsert` trigger of Sales Header (Table 36)
+- **Integration**: Must integrate with existing `Sales Order Processing` codeunit (50200)
+- **Posting**: Use standard BC posting framework, not custom posting logic
+- **Permissions**: Requires read access to Customer table, write to custom audit log
+```
+
+### 4. Data Model & Relationships
+Explicitly define table relationships and key fields:
+
+```markdown
+## Data Model
+- `MyTable` relates to `Customer` (Table 18) via `Customer No.` field
+- `Status` field (Option): Open=0, Released=1, Completed=2, Archived=3
+- `Document No.` must use number series from `MyTable Setup` (Table 50110)
+- FlowField: `Amount Including VAT` = SUM(MyTable Line.Amount Including VAT WHERE(Document No.=FIELD(Document No.)))
+```
+
+### 5. Standards & Patterns from Layers
+Leverage knowledge from your BC Code Intelligence layers:
+
+```markdown
+## Implementation Standards
+Per team layer (`domains/data-architecture/table-design-standards.md`):
+- All master tables must have SystemId, SystemCreatedAt, SystemModifiedAt
+- Description fields: Text[100], never Text[50]
+- Amount fields: Always Decimal with AutoFormatType = 1
+- Status fields: Use Option type with clear enum values
+
+Per company layer (`domains/error-handling/validation-patterns.md`):
+- Input validation in OnValidate triggers
+- Error messages via Error() not Message()
+- Use Error(Text000, FieldValue) pattern with text constants
+```
+
+### 6. API & Integration Requirements
+If the task involves APIs or integrations:
+
+```markdown
+## API Requirements
+- REST endpoint pattern: `/api/v2.0/companies({companyId})/myTables({id})`
+- Follow BC OData conventions (NavigationProperty for related entities)
+- Support $filter, $expand, $select query parameters
+- Page Type: API (PageType = API)
+- EntityName: 'myTable', EntitySetName: 'myTables'
+```
+
+### 7. Test Requirements
+Specify testing expectations:
+
+```markdown
+## Testing Requirements
+- Unit tests: Validate field validation logic (use AL Test Codeunits)
+- Test scenario: Create record with invalid Customer No., expect error
+- Test scenario: Post document, verify ledger entries created correctly
+- Edge case: Handle zero-quantity lines gracefully
+```
+
+## Complete Issue Template for Copilot Agent Handoff
+
+```markdown
+# Implement Sales Priority Management
+
+## Context
+We need to track priority levels for sales orders to optimize warehouse picking.
+
+## Object Details
+- **Table**: `Sales Priority` (Table 50100)
+  - Fields:
+    - Priority Code (Field 10, Code[10], Primary Key)
+    - Description (Field 20, Text[100])
+    - Warehouse Priority (Field 30, Integer, Range: 1-10)
+    - Is Default (Field 40, Boolean)
+- **Page**: `Sales Priority List` (Page 50100, PageType: List)
+- **Page**: `Sales Priority Card` (Page 50101, PageType: Card)
+- **Table Extension**: `Sales Header Ext` (TableExtension 50100, Extends: Sales Header)
+  - New Field: Priority Code (Field 50100, Code[10], TableRelation to Sales Priority)
+
+## Naming Conventions (Company Standard)
+- Prefix: `ABC_` for all custom objects
+- Field names: Space-separated words (`Priority Code` not `PriorityCode`)
+- Variables: Full descriptive names (`SalesPriorityRecord` not `SPRec`)
+- See: `company-layer/domains/naming-conventions/object-naming.md`
+
+## Implementation Requirements
+1. **Table Design**:
+   - Follow BC best practices: Include SystemId, Created/Modified audit fields
+   - Add standard Description field (Text[100])
+   - Warehouse Priority: Integer 1-10, with validation
+   - Only one record can have `Is Default = true` (validate on insert/modify)
+
+2. **Pages**:
+   - List page: Show all priorities, editable grid
+   - Card page: Full details, actions for Set as Default
+   - Both pages: Follow BC standard page patterns (FastTabs, FactBoxes)
+
+3. **Sales Integration**:
+   - Extend Sales Header with Priority Code field
+   - Default to "Is Default" priority on new sales orders
+   - Add Priority Code to Sales Order page (visible, editable)
+
+4. **Validation Rules**:
+   - Priority Code: Cannot be blank
+   - Warehouse Priority: Range 1-10, error if outside range
+   - Is Default: Only one record can be default (validate via code)
+
+5. **Permissions**:
+   - Create permission set: `ABC Sales Priority` (PermissionSet 50100)
+   - Grant read/insert/modify/delete on Sales Priority table
+   - Grant modify on Sales Header (for Priority Code field)
+
+## Business Logic
+- When `Is Default` is set to `true`, set all other records' `Is Default` to `false`
+- On Sales Header insert, default `Priority Code` from Sales Priority where `Is Default = true`
+- Validate that Priority Code exists in Sales Priority table
+
+## Testing Scenarios
+1. Create multiple priority records, verify only one can be default
+2. Create new sales order, verify priority defaults correctly
+3. Change priority on sales order, verify updates work
+4. Delete priority that's in use on sales order, expect error
+
+## Company-Specific Context
+Per company layer standards:
+- Error handling: Use Error(Text constants) pattern
+- Table design: Include audit fields (SystemCreatedAt, SystemModifiedAt)
+- Validation: OnValidate triggers, not in business logic codeunits
+- See: `company-layer/domains/error-handling/validation-patterns.md`
+
+## Expected Deliverables
+- [ ] Table 50100: Sales Priority
+- [ ] Page 50100: Sales Priority List
+- [ ] Page 50101: Sales Priority Card
+- [ ] TableExtension 50100: Sales Header with Priority Code field
+- [ ] PageExtension: Sales Order page showing Priority Code
+- [ ] PermissionSet 50100: ABC Sales Priority
+- [ ] Basic AL test codeunit validating default priority logic
+```
+
+## Context Extraction from BC Code Intelligence Layers
+
+When you have company/team layers loaded, extract this context for Issues:
+
+### From Layer: Naming Conventions
+```markdown
+Per company naming standards:
+- Object prefixes: [Extract from layer]
+- Field naming pattern: [Extract from layer]
+- Variable conventions: [Extract from layer]
+```
+
+### From Layer: Data Architecture
+```markdown
+Per company table design standards:
+- Required audit fields: [Extract from layer]
+- Field type standards: [Extract from layer]
+- Key/index patterns: [Extract from layer]
+```
+
+### From Layer: Error Handling
+```markdown
+Per company error handling patterns:
+- Validation approach: [Extract from layer]
+- Error message format: [Extract from layer]
+- Exception handling: [Extract from layer]
+```
+
+### From Layer: API Design
+```markdown
+Per company API patterns:
+- Endpoint conventions: [Extract from layer]
+- Query parameter support: [Extract from layer]
+- Response formats: [Extract from layer]
+```
+
+## Anti-Patterns: What NOT to Do
+
+❌ **Vague Requirements**
+```markdown
+# Bad Issue
+Add a priority field to sales orders.
+```
+**Problem**: No object IDs, no naming conventions, no data types, no validation rules.
+
+❌ **Missing Object IDs**
+```markdown
+# Bad Issue
+Create a Sales Priority table and pages.
+```
+**Problem**: Copilot Agent will guess object IDs, likely causing conflicts.
+
+❌ **No Naming Standards**
+```markdown
+# Bad Issue
+Create table SalesPrio with field PrioCode.
+```
+**Problem**: Doesn't follow company conventions, creates technical debt.
+
+❌ **Ignoring Layer Context**
+```markdown
+# Bad Issue
+Implement sales priority. Use standard BC patterns.
+```
+**Problem**: "Standard BC patterns" is vague. Company layer has specific patterns to follow.
+
+## Best Practices for AI-to-AI Handoff
+
+### 1. Front-Load All Context
+Copilot Agents can't ask follow-up questions. Assume they need:
+- Exact object IDs and names
+- Complete naming conventions
+- All business rules and validations
+- Technical constraints (field types, ranges, relationships)
+
+### 2. Reference Layer Knowledge
+When you have company/team layers:
+```markdown
+See company layer: `domains/naming-conventions/field-naming.md`
+See team layer: `domains/api-design/rest-endpoint-patterns.md`
+```
+This ensures consistency across development.
+
+### 3. Provide Examples
+Include code snippets showing expected patterns:
+```al
+// Expected validation pattern (per company standards):
+trigger OnValidate()
+begin
+    if "Warehouse Priority" < 1 or "Warehouse Priority" > 10 then
+        Error(OutsideOfAcceptablePriorityRangeErr, "Warehouse Priority", 1, 10);
+end;
+```
+
+### 4. Specify Acceptance Criteria
+Clear, testable outcomes:
+```markdown
+## Acceptance Criteria
+- [ ] Sales Priority table created with specified fields
+- [ ] Only one record can have Is Default = true
+- [ ] New sales orders default to default priority
+- [ ] Unit tests pass for validation scenarios
+```
+
+### 5. Link to Existing Code
+If extending existing functionality:
+```markdown
+## Related Code
+- Extend: Sales Header (Table 36)
+- Pattern reference: Customer table (Table 18) for master data example
+- Integration point: Release Sales Document codeunit (Codeunit 414)
+```
+
+## Integration with BC Code Intelligence Workflow
+
+### Step 1: Discover Standards
+Before creating the Issue, query your loaded layers:
+```
+Ask: "What are our company naming conventions for custom tables?"
+Ask: "What validation patterns should I use per our team standards?"
+```
+
+### Step 2: Gather Object Context
+Collect exact object information:
+```
+Ask: "What's our next available object ID in the 50100-50199 range?"
+Ask: "What's the standard pattern for master data tables?"
+```
+
+### Step 3: Craft Issue
+Use the template above, incorporating layer-specific context.
+
+### Step 4: Assign to Copilot Agent
+Create GitHub Issue, assign to @copilot-agent, label appropriately.
+
+### Step 5: Review Output
+When Copilot Agent completes:
+- Verify naming conventions match layer standards
+- Check object IDs are correct
+- Validate business logic implementation
+- Ensure error handling follows patterns
+
+## Version Compatibility
+
+- **BC 14+**: GitHub Copilot Agents support AL language
+- **BC 18+**: API page types, system fields
+- **BC 19+**: Enhanced enum support
+
+## See Also
+- [Naming Conventions](../shared/naming-conventions.md) - Standard naming patterns
+- [Object Numbering](../shared/object-numbering.md) - Object ID ranges and management
+- [Table Design Best Practices](../data-architecture/table-design.md) - BC table patterns
+- [Error Handling Patterns](../error-handling/validation.md) - Validation and error messages
+- [Alex Architect Specialist](../../specialists/alex-architect.md) - Strategic planning and delegation
+
+## Summary
+
+Effective delegation to GitHub Copilot Agents requires **comprehensive upfront context**. As an architect, your role is to translate strategic requirements into detailed, actionable Issues that include:
+
+1. **Exact object specifications** (IDs, names, types)
+2. **Naming conventions** (from company/team layers)
+3. **Business rules** (validation, logic, relationships)
+4. **Standards compliance** (error handling, patterns, architecture)
+5. **Acceptance criteria** (testable outcomes)
+
+By leveraging BC Code Intelligence layers and following these patterns, you ensure Copilot Agents produce code that integrates seamlessly with your organization's standards and architecture.

package/embedded-knowledge/domains/alex-architect/object-id-ninja-integration.md

@@ -0,0 +1,281 @@
+---
+title: "AL Object ID Ninja MCP Integration"
+domain: "alex-architect"
+bc_versions: "14+"
+difficulty: "intermediate"
+tags: ["object-ids", "mcp-integration", "id-management", "team-collaboration", "tooling"]
+related_topics:
+  - "../shared/object-id-ranges.md"
+  - "../../domains/shared/naming-conventions.md"
+applies_to:
+  - "AL Language"
+  - "Multi-Developer Teams"
+  - "AppSource Development"
+last_updated: "2025-10-27"
+conditional_mcp: "al-objid-mcp-server"
+---
+
+# AL Object ID Ninja MCP Integration
+
+## Overview
+
+When the **AL Object ID Ninja MCP** (`al-objid-mcp-server`) is available in your environment, you have access to intelligent object ID collision prevention and management. This topic explains when to delegate ID management to Object ID Ninja vs. handling it within BC Code Intelligence.
+
+**Key Principle**: Object ID Ninja is the specialist tool for ID collision prevention - always defer to it when available.
+
+## When Object ID Ninja is Available
+
+### **Detection**
+
+Check if Object ID Ninja is in the available MCPs list:
+```
+get_workspace_info()
+// Returns: { available_mcps: ["al-objid-mcp-server", ...] }
+```
+
+### **What Object ID Ninja Provides**
+
+**LITE Mode** (Individual Developers):
+- Local object ID pool management
+- Collision detection within workspace
+- Auto-suggestion of next available IDs
+- Git integration for app identification
+
+**STANDARD Mode** (Teams):
+- Backend integration for shared ID pools
+- Team-wide collision prevention
+- Real-time ID reservation
+- Multi-developer coordination
+
+### **When to Delegate to Object ID Ninja**
+
+✅ **ALWAYS delegate** when user asks about:
+- "What object IDs should I use?"
+- "Get me the next available ID for a table"
+- "Check if object ID X is available"
+- "Reserve object IDs for my feature"
+- "Set up object ID management for the team"
+
+✅ **Object ID Ninja Tools** (examples - actual tool names may vary):
+- `objid_get_next_available` - Get next free ID in range
+- `objid_reserve_id` - Reserve ID for object
+- `objid_check_availability` - Check if ID is free
+- `objid_configure_ranges` - Set up ID ranges for teams/apps
+
+### **Delegation Pattern**
+
+```markdown
+**Alex's Response:**
+"I see you have AL Object ID Ninja available in your environment. This is perfect for object ID management!
+
+Let me check the next available table ID for you using Object ID Ninja..."
+
+[Use Object ID Ninja MCP tool to get next ID]
+
+"Object ID Ninja suggests table ID 50100. This ID is available and reserved for your use."
+```
+
+### **Why Delegate?**
+
+1. **Real-Time Data**: Object ID Ninja has live backend connection for team coordination
+2. **Collision Prevention**: Prevents simultaneous ID claims by multiple developers
+3. **Range Management**: Understands configured ranges for different apps/teams
+4. **Git Integration**: Auto-detects app context from repository
+5. **Reservation System**: Locks IDs once assigned to prevent conflicts
+
+## When Object ID Ninja is NOT Available
+
+### **Fallback Strategy**
+
+If `al-objid-mcp-server` is NOT in `available_mcps`:
+
+✅ **BC Code Intelligence provides**:
+- General ID range guidance (50000-99999 for customizations)
+- AppSource range recommendations
+- Best practices for ID organization
+- Manual collision avoidance strategies
+
+✅ **Alex's Fallback Response**:
+```markdown
+"For object ID management, I recommend following these Business Central guidelines:
+
+**Custom Object Ranges:**
+- Tables: 50000-99999
+- Pages: 50000-99999
+- Reports: 50000-99999
+- Codeunits: 50000-99999
+
+**AppSource Apps:**
+- Must use assigned publisher range from Microsoft
+
+**Best Practices:**
+- Reserve ranges by feature or module (e.g., 50100-50199 for Sales Priority)
+- Document ID assignments in a shared spreadsheet or wiki
+- Check existing objects before assigning new IDs: `Get-ChildItem -Recurse *.al | Select-String 'table 50100'`
+
+**Team Recommendation:** 
+Consider installing AL Object ID Ninja MCP for automated collision prevention and team coordination. It provides real-time ID management with backend synchronization.
+
+[Installation: https://alguidelines.dev/docs/agentic-coding/communityresources/tools/al-objid-mcp-server/]
+```
+
+### **What NOT to Do Without Object ID Ninja**
+
+❌ **Don't claim** to reserve IDs (we can't - no backend)
+❌ **Don't guarantee** ID availability (can't check team's live pool)
+❌ **Don't suggest** specific IDs without caveat about manual verification
+
+## Architecture Guidance with Object ID Ninja
+
+### **Project Setup**
+
+When designing new apps/features with Object ID Ninja available:
+
+1. **Configure ID Ranges First**
+```markdown
+"Before we start creating objects, let's set up your ID ranges with Object ID Ninja..."
+
+[Use objid_configure_ranges tool]
+
+"I've configured:
+- Sales Priority Module: Tables 50100-50149, Pages 50100-50149
+- Inventory Extension: Tables 50150-50199, Pages 50150-50199"
+```
+
+2. **Request IDs During Design**
+```markdown
+"For your Sales Priority Management feature, we need:
+- 1 Table (Customer Priority Levels)
+- 2 Pages (Priority Setup, Priority List)
+- 1 Codeunit (Priority Calculator)
+
+Let me request these IDs from Object ID Ninja..."
+
+[Use objid_get_next_available for each object type]
+
+"Object ID Ninja has assigned:
+- Table 50100 - Customer Priority Levels
+- Page 50100 - Customer Priority Setup
+- Page 50101 - Customer Priority List
+- Codeunit 50100 - Priority Calculator"
+```
+
+### **App.json Integration**
+
+Object ID Ninja can auto-detect app context from Git, but you can also specify:
+
+```json
+{
+  "id": "12345678-1234-1234-1234-123456789012",
+  "name": "SalesPriorityManager",
+  "publisher": "Contoso",
+  "version": "1.0.0.0",
+  "idRanges": [
+    {
+      "from": 50100,
+      "to": 50199
+    }
+  ]
+}
+```
+
+Object ID Ninja respects these configured ranges.
+
+## Team Collaboration Patterns
+
+### **Multi-Developer Scenario**
+
+**Without Object ID Ninja:**
+- Developers manually coordinate via spreadsheet/wiki
+- Risk of simultaneous ID claims
+- Merge conflicts when IDs collide
+
+**With Object ID Ninja (STANDARD mode):**
+- Backend automatically coordinates ID assignments
+- Developers get unique IDs instantly
+- No coordination overhead
+- Zero collision risk
+
+### **Code Review Guidance**
+
+When reviewing PRs with Object ID Ninja available:
+
+```markdown
+"Let me verify the object IDs in this PR are properly reserved..."
+
+[Use objid_check_availability for each ID]
+
+✅ "All object IDs (50100-50103) are validly reserved to this developer."
+
+OR
+
+⚠️ "Table 50105 is not reserved to you - it's assigned to another developer. Let's get you a different ID..."
+
+[Use objid_get_next_available to suggest alternative]
+```
+
+## AppSource Development
+
+### **Publisher Range Management**
+
+**With Object ID Ninja:**
+```markdown
+"For AppSource submission, you need a dedicated publisher range from Microsoft.
+
+Once you have your range (e.g., 70000-70999), configure it in Object ID Ninja..."
+
+[Use objid_configure_ranges with publisher range]
+
+"Now Object ID Ninja will only assign IDs from your approved publisher range, ensuring AppSource compliance."
+```
+
+**Without Object ID Ninja:**
+```markdown
+"For AppSource, contact Microsoft to get your publisher ID range assignment.
+
+Manually verify all objects fall within your assigned range before submission. Document your range in app.json idRanges."
+```
+
+## Recommendations and Handoffs
+
+### **When to Recommend Object ID Ninja**
+
+Suggest installation if user mentions:
+- "We keep having ID conflicts"
+- "How do we coordinate IDs across the team?"
+- "Manual ID tracking is painful"
+- "Can AI help with object ID management?"
+
+### **Installation Guidance**
+
+```markdown
+"Your team would benefit greatly from AL Object ID Ninja MCP!
+
+**Benefits:**
+- Automatic ID collision prevention
+- Team-wide coordination (STANDARD mode)
+- Git integration for auto-detection
+- Real-time ID reservation
+
+**Installation:**
+1. Visit: https://alguidelines.dev/docs/agentic-coding/communityresources/tools/al-objid-mcp-server/
+2. Choose LITE (individual) or STANDARD (team backend) mode
+3. Configure in your MCP client (VS Code, Claude Desktop, etc.)
+4. Restart and provide available_mcps when calling set_workspace_info
+
+Once installed, I'll be able to request IDs directly from Object ID Ninja for you!"
+```
+
+## Best Practices
+
+1. **Always Check Availability**: Use `get_workspace_info()` at conversation start to detect MCP ecosystem
+2. **Transparent Delegation**: Tell user "I'm using Object ID Ninja to..." when delegating
+3. **Fallback Gracefully**: Provide manual guidance when Object ID Ninja not available
+4. **Encourage Adoption**: Recommend Object ID Ninja for teams with ID management pain
+5. **Trust the Specialist**: Object ID Ninja's ID assignments are authoritative - don't second-guess them
+
+## See Also
+
+- [Object ID Ranges](../shared/object-id-ranges.md) - Standard BC object ID ranges
+- [Naming Conventions](../../domains/shared/naming-conventions.md) - Object naming standards
+- [AL Object ID Ninja MCP Documentation](https://alguidelines.dev/docs/agentic-coding/communityresources/tools/al-objid-mcp-server/)