Transition AI Tooling to a Specialized Multi-Agent and Skill-Driven Ecosystem

[pedrazamiguez]

Problem / Motivation

• Context Window Contention & Hallucination Risks: Monolithic command prompts attempt to handle requirement ingestion, domain modeling, implementation, and quality verification in a single context window. This creates cognitive load on the LLM and increases the risk of subtle architectural degradation.
• Lack of Domain Grounding: Business invariants, bounded contexts, and Architectural Decision Records (ADRs) are not consistently maintained as a living, version-controlled Single Source of Truth accessible directly to the model during execution.
• Underutilized MCP Orchestration: Configured MCP integrations (GitHub, Firebase Firestore, Stitch with Google) operate as isolated tools rather than orchestrated steps within an automated agent pipeline.
• Single-Pass Execution vs. Phased SDD: Specification-Driven Development (SDD) requires clear boundaries between specification, interface design, domain implementation, UI wiring, and automated verification. Single-pass prompt invocations bypass these discrete phases.

Proposed Solution

Migrate toward a modular multi-agent architecture with dedicated skills, strict domain grounding, and orchestrated Model Context Protocol (MCP) integrations.

• Domain & Context Grounding: Establish a structured directory (e.g., /docs/domain/ and /docs/architecture/adrs/) containing living, machine-readable specifications of core domain entities, value objects, and invariant rules. Inject these as read-only grounding context.
• Specialized Agent Roles:
  • Specification Agent: Analyzes the initial brief, retrieves existing domain rules, and outputs a formal SDD change specification.
  • Architect Agent: Defines public interfaces, domain contracts, and Use Case signatures adhering strictly to Clean/Hexagonal Architecture.
  • Domain Implementer: Implements pure business logic, invariants, and comprehensive unit tests using TDD principles. Zero platform dependencies allowed.
  • Infra & UI Implementer: Connects repositories, external data sources, and Compose UI components according to visual tokens and backend schemas.
  • Auditor / QA Agent: Executes architectural guardrail tests, static analysis (detekt, ktlint), and verifies zero regressions or code smells.
• Migration Roadmap:
  1. Audit existing prompts to map inputs, outputs, and implicit rules into discrete functional skills.
  2. Consolidate domain rules, ubiquitous language, and ADRs into a standardized markdown structure.
  3. Encapsulate common tasks into reusable, self-contained skills.
  4. Execute an end-to-end SDD lifecycle for a single feature branch as a pilot.
  5. Verify generated code passes all architectural tests and static checks automatically.

Acceptance Criteria

• Existing Antigravity and opencode prompts are audited and cataloged.
• Domain rules and ADRs are formalized in a standardized markdown structure within the project tree (e.g., /docs/domain/, /docs/architecture/adrs/).
• Reusable, self-contained skills are defined for common tasks (Use Case creation, Compose screen scaffolding, architectural validation runs).
• An end-to-end SDD lifecycle is successfully executed for a single feature branch using the new agentic workflow.
• All existing tests pass; new tests added where behaviour changes.
• make fast-check passes during iterative development (~15–30s).
• make check > build.log 2>&1 && echo "Check passed successfully" || (tail -n 100 build.log && exit 1) passes with 0 failures before merging.
• No new detekt findings introduced.

Out of Scope

• Rewriting existing application code or features that are already implemented.
• Changing the underlying Android architecture (Clean Architecture, MVI, etc.) of the application itself.

[github-actions]

🌱 Branch created

refactor/SPLTRP-1518

This branch has been automatically created based on develop.

🚀 Getting started

Fetch and switch to this branch with the latest changes from develop:

git fetch origin
git checkout refactor/SPLTRP-1518
git pull origin develop

📌 When creating your PR

• Base branch: develop
• Title:

  [SPLTRP-1518]: Transition AI Tooling to a Specialized Multi-Agent and Skill-Driven Ecosystem
  

• Description: Closes #1518

[pedrazamiguez]

Context for Implementation:
When planning the transition, we need to take into account what we already have and the current directory structure. Please consider the following folders in the audit and consolidation phases:

• .agents/skills: Currently houses our skills (though these are likely just prompts that need to be evaluated and integrated into the new skill-driven ecosystem).
• docs: We should evaluate unifying the wiki folder into this docs directory to have a single source of truth.
• wiki: Contains articles on project decisions, domain logic, the services catalog, etc. This is currently a mix of information that we need to properly categorize and structure according to the new domain grounding requirements.