Quartz 4

AGENTS

3 min read

MILTON Project Context

This is the MILTON system: a multi-service .NET application for AI-powered documentation generation with traceability between documents.

Service Map

ServiceProjectResponsibility
APIMILTON/Main ASP.NET Core API; owns milton-db and core business logic
ClusteringMILTON.Clustering/Python FastAPI code analysis + C# proxy endpoints
DocumentGeneratorMILTON.DocumentGenerator/Wolverine worker for AI document generation
GitOperationsMILTON.GitOperations/Wolverine worker for Git clone / analysis / S3 upload
NotificationServiceMILTON.NotificationService/SignalR + Wolverine real-time notifications
ReactClientMILTON.ReactClient/React + TypeScript frontend
PlatformMILTON.Platform/Shared AI and storage abstractions
ServiceDefaultsMILTON.ServiceDefaults/Shared Aspire/service defaults
AppHostMILTON.AppHost/.NET Aspire orchestration
McpServerMILTON.McpServer/MCP server exposing MILTON knowledge graph
KnowledgeSeedingServiceMILTON.KnowledgeSeedingService/Neo4j/PGVector seeding worker

Which Mode Are You In?

  • Orchestrator (Tech Lead) mode — You are running as the tech-lead agent, or the user has asked for work to be planned and delegated. Do not read or modify code directly: plan the contracts, collaborate on Acceptance Criteria, then delegate to domain expert subagents (api-agent, documentgenerator-agent, etc.).
  • Direct mode — Default for a normal session. The user is talking directly to you and expects you to do the work. Implement it yourself; do not spin up subagents unless explicitly asked.

If you are unsure which mode you are in, you are in direct mode.

The milton-knowledge MCP Server

Prioritize the milton-knowledge MCP server tools (search_code_context, get_system_architecture_map, get_service_dependencies_map) before exploring or modifying code across services.

  • Vector Database Search (search_code_context):
    • Global/Feature namespaces: query system architecture and codebase concepts.
    • Dedicated external namespaces: specify agentNamespace to access framework docs (framework_docs), frontend docs (frontend_docs), or security standards (security).
    • HARD RULE: When evaluating security, performance, or compliance, query the security namespace (OWASP Top 10) to retrieve project baseline standards before auditing code.
  • Do Not Brute-Force Code Sweeps: Unless a specific path is named, use vector search or graph tools first rather than speculative grep sweeps.

Universal Conventions & Constraints

  • Vertical Slice Architecture: One self-contained directory per capability.
  • CQRS with Wolverine: Per-producer [MessageIdentity] records bound at the wire.
  • Test-Driven Development (TDD): Failing test first → minimal implementation → refactor green.
  • No External CDNs: All frontend assets (CSS, JS, fonts) must be vendored locally for air-gapped environments.
  • Platform-Agnostic Paths: Always use Path.Combine(), never hardcoded / or \ string concatenation.
  • No Hardcoded Secrets: Use IConfiguration with user secrets or environment variables.
  • Offline-First: Avoid calling external APIs unless explicitly mandated by the architecture.

Git Workflow & Lifecycle (Mandatory)

  • Issue-first: Every non-trivial change starts as a GitHub issue with Acceptance Criteria and Definition of Done (Closes #N).
  • Base PRs on dev: dev is the integration branch; main is the release branch.
  • PR Delegation: Only the Tech Lead merges PRs into dev.
  • Stacked PRs: For multi-part work, use gh-stack to keep changes reviewable.
  • Commit Messages: Follow Conventional Commits (feat:, fix:, docs:, etc.).

Work Item Lifecycle

GitHub issue (AC + DoD) → Kanban task (assigned to domain agent)
→ Worker implements (TDD) → PR (Closes #N, base dev) → Tech Lead review & merge
→ Issue closed

System Commands & Aspire Basics

# Run full application via Aspire
aspire run
 
# Build solution
dotnet build --configuration Release
 
# Run test suite
dotnet test --no-build --configuration Release --verbosity normal
  • Aspire Diagnostics: When inspecting application issues, use Aspire log tools (list_console_logs, list_structured_logs, list_traces) before modifying app host or service code.

Graph View

Backlinks