cardosofelipe/syndarix
1
0
Fork 0
forked from cardosofelipe/fast-next-template
Code Issues 18 Pull Requests Wiki Activity
Files
dev
syndarix/docs/requirements/SYNDARIX_REQUIREMENTS.md
Felipe Cardoso 29309e5cfd docs: Add missing architecture flow and update roadmap for dashboard/onboarding 
Requirements:
- Add 6.4.3 Architecture Spike & Proposal Flow diagram
- Documents the flow from approved requirements → collaborative brainstorm →
  proposal → client approval → ADRs → sprint planning

Implementation Roadmap:
- Add Phase 1.5: Main Dashboard & Onboarding section
- Add issues #47-50 for main dashboard and project creation wizard
- Update progress summary (Phase 1 now at ~75%)
- Add blocking items for new design work

Related Issues:
- #47: [DESIGN] Main Dashboard / Projects List Page
- #48: Implement Main Dashboard / Projects List Page
- #49: [DESIGN] Project Creation Wizard
- #50: Implement Project Creation Wizard

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-30 18:32:31 +01:00

2570 lines
95 KiB
Markdown
Raw Permalink Blame History

# Syndarix Requirements Document
**Version:** 2.0
**Last Updated:** 2025-12-29
**Status:** Approved
**Document Owner:** Product Team
---
## Table of Contents
1. [Executive Summary](#1-executive-summary)
2. [Problem Statement and Objectives](#2-problem-statement-and-objectives)
3. [Stakeholder Analysis](#3-stakeholder-analysis)
4. [Functional Requirements](#4-functional-requirements)
5. [Non-Functional Requirements](#5-non-functional-requirements)
6. [System Architecture Overview](#6-system-architecture-overview)
7. [Data Requirements](#7-data-requirements)
8. [Integration Requirements](#8-integration-requirements)
9. [User Stories and Use Cases](#9-user-stories-and-use-cases)
10. [Acceptance Criteria](#10-acceptance-criteria)
11. [Constraints and Assumptions](#11-constraints-and-assumptions)
12. [Risks and Mitigations](#12-risks-and-mitigations)
13. [Success Metrics](#13-success-metrics)
14. [Glossary](#14-glossary)
---
## 1. Executive Summary
### 1.1 Vision Statement
Syndarix is an AI-powered software consulting agency platform that orchestrates specialized AI agents to deliver complete software solutions autonomously. It transforms the software development lifecycle by providing a virtual consulting team where AI agents collaboratively plan, design, implement, test, and deliver software with minimal human intervention.
### 1.2 Key Objectives
| Objective | Description | Success Metric |
|-----------|-------------|----------------|
| **OBJ-001** | Reduce manual project management overhead | 80% reduction in PM time per project |
| **OBJ-002** | Deliver production-ready code autonomously | 90% of deliverables pass first review |
| **OBJ-003** | Maintain full transparency and client control | 100% artifact visibility, intervention at any point |
| **OBJ-004** | Support varying client technical proficiency | Both technical and "auto" modes functional |
| **OBJ-005** | Scale to multiple concurrent projects | Support 10+ active projects per instance |
### 1.3 Target Audience
- **Primary:** Internal development teams seeking AI-augmented development
- **Secondary:** Company stakeholders requiring software solutions
- **Future:** External clients (post-v1, if multi-tenant support added)
### 1.4 Scope Summary
**In-Scope (v1):**
- Multi-agent orchestration with 10 specialized roles
- Complete SDLC workflow automation
- Configurable autonomy levels
- MCP-first architecture for all integrations
- Project complexity wizard (Script/Simple/Medium/Complex)
- Full artifact delivery (code, docs, ADRs, tests)
**Out-of-Scope (v1):**
- Multi-tenant SaaS deployment
- Public API access
- Mobile application
- Real-time video collaboration
- Third-party marketplace integrations
---
## 2. Problem Statement and Objectives
### 2.1 Problem Statement
Modern software development faces a paradox: despite advances in AI coding assistants, developers spend as much time managing AI as doing the work themselves. Key pain points include:
1. **Context Switching Overhead:** Developers constantly switch between tools, losing context and productivity
2. **Knowledge Fragmentation:** Project knowledge scattered across conversations, documents, and code
3. **AI Babysitting:** Current AI tools require constant human guidance and validation
4. **Inconsistent Quality:** No standardized process for AI-generated code review and testing
5. **Missing Orchestration:** No unified system to coordinate multiple AI capabilities
6. **Limited Autonomy:** Existing tools cannot handle end-to-end project delivery
### 2.2 Proposed Solution
Syndarix addresses these challenges through:
1. **Structured Agency Model:** Specialized AI agents with defined roles, expertise, and communication protocols
2. **Unified Knowledge Base:** Centralized, searchable repository with project and agent scoping
3. **Autonomous Workflows:** Agents work independently with checkpoints for human intervention
4. **Quality Gates:** Built-in review processes, testing requirements, and approval workflows
5. **MCP Orchestration:** Single integration layer for all external tools and services
6. **Configurable Control:** Client-defined autonomy levels from full control to fully autonomous
### 2.3 Value Proposition
| Stakeholder | Value Delivered |
|-------------|-----------------|
| **Developers** | Focus on creative work while AI handles routine tasks |
| **Project Managers** | Automated backlog management, sprint planning, and progress tracking |
| **Business Owners** | Faster time-to-market with consistent quality |
| **Architects** | AI-assisted design with ADR documentation |
| **QA Teams** | Automated test generation and execution |
### 2.4 Business Objectives
| ID | Objective | Target | Timeline |
|----|-----------|--------|----------|
| **BO-001** | Reduce project delivery time | 50% faster | Q2 2025 |
| **BO-002** | Decrease bug density in production | 40% reduction | Q3 2025 |
| **BO-003** | Improve documentation coverage | 95% coverage | Q2 2025 |
| **BO-004** | Enable non-technical stakeholders to request features | 100% accessibility | Q2 2025 |
| **BO-005** | Maintain full auditability and compliance | SOC2-ready processes | Q4 2025 |
---
## 3. Stakeholder Analysis
### 3.1 Human Stakeholders
#### 3.1.1 Client (Human User)
| Attribute | Description |
|-----------|-------------|
| **Role** | Project requester and primary beneficiary |
| **Responsibilities** | Define requirements, approve milestones, provide feedback |
| **Technical Proficiency** | Varies: Technical (detailed specs) or Auto (high-level goals) |
| **Interaction Mode** | Web UI, chat interface, approval workflows |
| **Success Criteria** | Receives complete, working software with all artifacts |
#### 3.1.2 System Administrator
| Attribute | Description |
|-----------|-------------|
| **Role** | Platform operator and maintainer |
| **Responsibilities** | Configure agents, manage integrations, monitor health |
| **Technical Proficiency** | High (DevOps/SRE level) |
| **Interaction Mode** | Admin panel, CLI, configuration files |
| **Success Criteria** | Stable platform operation, successful agent orchestration |
### 3.2 AI Agent Stakeholders
Each agent type represents a specialized role in the software development lifecycle. Agents can be spawned as multiple instances with unique identities and domain knowledge.
#### 3.2.1 Product Owner Agent
| Attribute | Description |
|-----------|-------------|
| **Primary Expertise** | Requirements elicitation, user story creation, prioritization |
| **Responsibilities** | Client communication, requirements definition, acceptance criteria |
| **Interactions** | Client (primary), Business Analyst, Project Manager, Architect |
| **Deliverables** | PRDs, user stories, acceptance criteria, feature prioritization |
| **Autonomy Level** | High (client-facing, but requires approvals for major decisions) |
#### 3.2.2 Project Manager Agent
| Attribute | Description |
|-----------|-------------|
| **Primary Expertise** | Backlog management, sprint planning, team coordination |
| **Responsibilities** | Sprint ceremonies, progress tracking, blocker resolution |
| **Interactions** | All agents, Client (status updates) |
| **Deliverables** | Sprint backlogs, burndown charts, status reports, meeting notes |
| **Autonomy Level** | High (operational decisions), Medium (scope changes) |
#### 3.2.3 Business Analyst Agent
| Attribute | Description |
|-----------|-------------|
| **Primary Expertise** | Requirements analysis, process modeling, documentation |
| **Responsibilities** | Detailed analysis, workflow documentation, gap analysis |
| **Interactions** | Product Owner, Architect, Software Engineers |
| **Deliverables** | Business requirements docs, process flows, data dictionaries |
| **Autonomy Level** | Medium (analysis), Low (business rule changes) |
#### 3.2.4 Software Architect Agent
| Attribute | Description |
|-----------|-------------|
| **Primary Expertise** | System design, technology selection, architectural patterns |
| **Responsibilities** | Architecture decisions, tech stack recommendations, ADRs |
| **Interactions** | Product Owner, Business Analyst, Software Engineers, DevOps |
| **Deliverables** | Architecture diagrams, ADRs, tech stack documentation, API designs |
| **Autonomy Level** | Medium (design decisions require client approval) |
#### 3.2.5 Software Engineer Agent
| Attribute | Description |
|-----------|-------------|
| **Primary Expertise** | Code implementation, code review, technical problem-solving |
| **Responsibilities** | Feature implementation, bug fixes, code reviews, unit tests |
| **Interactions** | Architect, QA Engineers, other Software Engineers |
| **Deliverables** | Source code, unit tests, code documentation, PR descriptions |
| **Autonomy Level** | High (implementation), Low (architectural changes) |
| **Instance Support** | Multiple instances (e.g., Dave, Ellis, Kate) with specializations |
#### 3.2.6 UI/UX Designer Agent
| Attribute | Description |
|-----------|-------------|
| **Primary Expertise** | User interface design, user experience, accessibility |
| **Responsibilities** | Wireframes, mockups, design systems, usability guidelines |
| **Interactions** | Product Owner, Software Engineers, QA Engineers |
| **Deliverables** | Wireframes, mockups, design tokens, accessibility specs |
| **Autonomy Level** | Medium (design choices require client feedback) |
#### 3.2.7 QA Engineer Agent
| Attribute | Description |
|-----------|-------------|
| **Primary Expertise** | Test planning, test automation, quality assurance |
| **Responsibilities** | Test case creation, test execution, bug reporting, coverage analysis |
| **Interactions** | Software Engineers, Product Owner, DevOps |
| **Deliverables** | Test plans, test cases, bug reports, coverage reports |
| **Autonomy Level** | High (testing decisions), Medium (release sign-off) |
#### 3.2.8 DevOps Engineer Agent
| Attribute | Description |
|-----------|-------------|
| **Primary Expertise** | CI/CD, infrastructure, deployment automation |
| **Responsibilities** | Pipeline setup, deployment scripts, monitoring, IaC |
| **Interactions** | Software Engineers, Architect, Security Expert |
| **Deliverables** | CI/CD pipelines, Dockerfiles, IaC configs, monitoring dashboards |
| **Autonomy Level** | Medium (infrastructure changes require approval) |
#### 3.2.9 AI/ML Engineer Agent
| Attribute | Description |
|-----------|-------------|
| **Primary Expertise** | Machine learning, model training, ML operations |
| **Responsibilities** | ML model development, training pipelines, model deployment |
| **Interactions** | Software Engineers, Architect, DevOps |
| **Deliverables** | ML models, training scripts, evaluation reports, MLOps pipelines |
| **Autonomy Level** | Medium (model decisions require validation) |
#### 3.2.10 Security Expert Agent
| Attribute | Description |
|-----------|-------------|
| **Primary Expertise** | Security review, vulnerability assessment, compliance |
| **Responsibilities** | Security audits, penetration testing, compliance checks |
| **Interactions** | All technical agents, Architect |
| **Deliverables** | Security reports, vulnerability assessments, remediation plans |
| **Autonomy Level** | High (security recommendations), Low (risk acceptance) |
### 3.3 Agent Configuration Model
```
+------------------+ spawns +-------------------+
| Agent Type |---------------->| Agent Instance |
+------------------+ +-------------------+
| - base_model | | - instance_id |
| - failover_model | | - name (e.g.Dave) |
| - expertise | | - project_id |
| - personality | | - domain_knowledge|
| - capabilities | | - conversation |
+------------------+ | - rag_context |
+-------------------+
```
### 3.4 Stakeholder Communication Matrix
| From/To | Client | PO | PM | BA | Arch | Eng | UX | QA | DevOps | AI/ML | Security |
|---------|--------|----|----|----|----|-----|----|----|--------|-------|----------|
| **Client** | - | Direct | Status | - | Review | - | Review | - | - | - | - |
| **PO** | Direct | - | Daily | Direct | Spike | Stories | Direct | Criteria | - | - | - |
| **PM** | Status | Daily | - | Tasks | Sync | Assign | Sync | Sync | Sync | Sync | Sync |
| **BA** | - | Direct | Tasks | - | Collab | Specs | Specs | Specs | - | - | - |
| **Arch** | Review | Spike | Sync | Collab | - | Guide | Consult | - | Direct | Direct | Direct |
| **Eng** | - | Stories | Status | Specs | Guide | PR | Impl | Bugs | Deploy | Collab | Review |
| **UX** | Review | Direct | Sync | Specs | Consult | Impl | - | Review | - | - | - |
| **QA** | - | Criteria | Sync | Specs | - | Bugs | Review | - | Test | - | Test |
| **DevOps** | - | - | Sync | - | Direct | Deploy | - | Test | - | MLOps | Infra |
| **AI/ML** | - | - | Sync | - | Direct | Collab | - | - | MLOps | - | Review |
| **Security** | - | - | Sync | - | Direct | Review | - | Test | Infra | Review | - |
---
## 4. Functional Requirements
### 4.1 Agent Management (FR-100 Series)
#### FR-101: Agent Type Configuration
| Attribute | Value |
|-----------|-------|
| **ID** | FR-101 |
| **Title** | Agent Type Configuration |
| **Description** | System shall allow administrators to define agent types with configurable base models, failover models, expertise areas, and personality profiles |
| **Priority** | Must Have |
| **Dependencies** | None |
**Acceptance Criteria:**
- [ ] AC-101.1: Admin can create new agent type with required fields (name, base_model, expertise)
- [ ] AC-101.2: Admin can specify failover model for each agent type
- [ ] AC-101.3: Admin can define expertise areas as searchable tags
- [ ] AC-101.4: Admin can configure personality profile (communication style, verbosity, tone)
- [ ] AC-101.5: System validates model availability before saving
- [ ] AC-101.6: Agent types can be activated/deactivated without deletion
#### FR-102: Agent Instance Spawning
| Attribute | Value |
|-----------|-------|
| **ID** | FR-102 |
| **Title** | Agent Instance Spawning |
| **Description** | System shall spawn agent instances from defined types with unique identities and project assignments |
| **Priority** | Must Have |
| **Dependencies** | FR-101 |
**Acceptance Criteria:**
- [ ] AC-102.1: System can spawn multiple instances from same agent type
- [ ] AC-102.2: Each instance has unique name (e.g., Dave, Ellis, Kate for Software Engineer)
- [ ] AC-102.3: Instances maintain separate conversation history
- [ ] AC-102.4: Instances can be assigned to specific projects
- [ ] AC-102.5: Instance count per type is configurable per project
- [ ] AC-102.6: Instances can be terminated and resources released
#### FR-103: Agent Domain Knowledge (RAG)
| Attribute | Value |
|-----------|-------|
| **ID** | FR-103 |
| **Title** | Agent Domain Knowledge via RAG |
| **Description** | System shall support per-instance domain knowledge customization through RAG (Retrieval-Augmented Generation) |
| **Priority** | Must Have |
| **Dependencies** | FR-102, FR-801 |
**Acceptance Criteria:**
- [ ] AC-103.1: Each instance can have unique RAG context loaded
- [ ] AC-103.2: Domain knowledge documents can be uploaded and indexed
- [ ] AC-103.3: RAG queries are scoped to project and agent
- [ ] AC-103.4: Knowledge base updates propagate to active instances
- [ ] AC-103.5: Instance can query shared project knowledge base
- [ ] AC-103.6: Query results include relevance scores and source attribution
#### FR-104: Agent Communication
| Attribute | Value |
|-----------|-------|
| **ID** | FR-104 |
| **Title** | Inter-Agent Communication |
| **Description** | System shall enable structured communication between agent instances with message routing and history |
| **Priority** | Must Have |
| **Dependencies** | FR-102 |
**Acceptance Criteria:**
- [ ] AC-104.1: Agents can send messages to specific agent instances
- [ ] AC-104.2: Agents can broadcast to all agents of a specific type
- [ ] AC-104.3: Messages are persisted with timestamps and metadata
- [ ] AC-104.4: Communication supports attachments (code, documents, artifacts)
- [ ] AC-104.5: Message threads are viewable by clients
- [ ] AC-104.6: Priority messaging for blockers and urgent items
#### FR-105: Agent Monitoring
| Attribute | Value |
|-----------|-------|
| **ID** | FR-105 |
| **Title** | Agent Activity Monitoring |
| **Description** | System shall provide real-time visibility into agent activities, resource usage, and performance |
| **Priority** | Should Have |
| **Dependencies** | FR-102 |
**Acceptance Criteria:**
- [ ] AC-105.1: Dashboard shows active agents per project
- [ ] AC-105.2: Real-time activity feed for each agent instance
- [ ] AC-105.3: Token usage and cost tracking per agent
- [ ] AC-105.4: Performance metrics (response time, success rate)
- [ ] AC-105.5: Error logging and alerting for agent failures
- [ ] AC-105.6: Historical activity reports exportable
### 4.2 Project Management (FR-200 Series)
#### FR-201: Project Creation Wizard
| Attribute | Value |
|-----------|-------|
| **ID** | FR-201 |
| **Title** | Project Creation Wizard |
| **Description** | System shall guide users through project creation with complexity assessment and automatic workflow configuration |
| **Priority** | Must Have |
| **Dependencies** | None |
**Acceptance Criteria:**
- [ ] AC-201.1: Wizard collects project name, description, and goals
- [ ] AC-201.2: Complexity assessment based on scope indicators
- [ ] AC-201.3: Four complexity levels supported: Script, Simple, Medium, Complex
- [ ] AC-201.4: Workflow automatically configured based on complexity
- [ ] AC-201.5: Client can override suggested complexity level
- [ ] AC-201.6: Project template selection for common project types
**Complexity Level Definitions:**
| Level | Git Repo | Sprints | Process | Agents |
|-------|----------|---------|---------|--------|
| **Script** | Optional | None | Minimal | 1-2 Engineers |
| **Simple** | Yes | 1 | Basic backlog | PO, PM, 2-3 Engineers, QA |
| **Medium** | Yes | 2-4 | Full AGILE | All roles |
| **Complex** | Yes | 5+ | Full AGILE + Architecture | All roles + specialists |
#### FR-202: Project Configuration
| Attribute | Value |
|-----------|-------|
| **ID** | FR-202 |
| **Title** | Project Configuration |
| **Description** | System shall allow detailed project configuration including tech stack, integrations, and team composition |
| **Priority** | Must Have |
| **Dependencies** | FR-201 |
**Acceptance Criteria:**
- [ ] AC-202.1: Tech stack selection with recommendations from Architect agent
- [ ] AC-202.2: Git provider configuration (Gitea/GitHub/GitLab)
- [ ] AC-202.3: Issue tracker selection (Gitea Issues/GitHub Issues/GitLab Issues)
- [ ] AC-202.4: CI/CD pipeline selection (Gitea Actions/GitHub Actions/GitLab CI)
- [ ] AC-202.5: Agent team composition customization
- [ ] AC-202.6: Autonomy level configuration
- [ ] AC-202.7: Notification preferences setup
#### FR-203: Autonomy Level Configuration
| Attribute | Value |
|-----------|-------|
| **ID** | FR-203 |
| **Title** | Autonomy Level Configuration |
| **Description** | System shall support configurable autonomy levels determining when client approval is required |
| **Priority** | Must Have |
| **Dependencies** | FR-201 |
**Acceptance Criteria:**
- [ ] AC-203.1: Three autonomy levels: FULL_CONTROL, MILESTONE, AUTONOMOUS
- [ ] AC-203.2: FULL_CONTROL requires approval for every significant action
- [ ] AC-203.3: MILESTONE requires approval at sprint boundaries and major decisions
- [ ] AC-203.4: AUTONOMOUS requires approval only for architecture and scope changes
- [ ] AC-203.5: Client can change autonomy level at any time
- [ ] AC-203.6: Client can intervene regardless of autonomy level
**Autonomy Level Matrix:**
| Action | FULL_CONTROL | MILESTONE | AUTONOMOUS |
|--------|--------------|-----------|------------|
| Requirements approval | Required | Required | Required |
| Architecture approval | Required | Required | Required |
| Sprint start | Required | Required | Auto |
| Story implementation | Required | Auto | Auto |
| PR merge | Required | Auto | Auto |
| Sprint completion | Required | Required | Auto |
| Bug fixes | Required | Auto | Auto |
| Documentation updates | Required | Auto | Auto |
#### FR-204: Client Proficiency Modes
| Attribute | Value |
|-----------|-------|
| **ID** | FR-204 |
| **Title** | Client Proficiency Modes |
| **Description** | System shall support both technical and "auto" modes for clients with varying technical expertise |
| **Priority** | Must Have |
| **Dependencies** | FR-201 |
**Acceptance Criteria:**
- [ ] AC-204.1: Technical mode allows detailed requirement specification
- [ ] AC-204.2: Auto mode accepts high-level goals ("just build it")
- [ ] AC-204.3: Auto mode triggers extended discovery process with PO agent
- [ ] AC-204.4: System adapts communication complexity to client mode
- [ ] AC-204.5: Client can switch modes mid-project
- [ ] AC-204.6: Technical details always available but optionally hidden in auto mode
### 4.3 Workflow Management (FR-300 Series)
#### FR-301: Requirements Discovery Workflow
| Attribute | Value |
|-----------|-------|
| **ID** | FR-301 |
| **Title** | Requirements Discovery Workflow |
| **Description** | System shall orchestrate a structured requirements discovery process between client and Product Owner agent |
| **Priority** | Must Have |
| **Dependencies** | FR-104, FR-201 |
**Acceptance Criteria:**
- [ ] AC-301.1: PO agent initiates discovery conversation with client
- [ ] AC-301.2: System guides through problem statement, goals, constraints
- [ ] AC-301.3: PO agent generates user stories from conversation
- [ ] AC-301.4: Acceptance criteria auto-generated for each story
- [ ] AC-301.5: Requirements document generated and presented for approval
- [ ] AC-301.6: Iteration supported until client approves requirements
#### FR-302: Architecture Spike Workflow
| Attribute | Value |
|-----------|-------|
| **ID** | FR-302 |
| **Title** | Architecture Spike Workflow |
| **Description** | System shall orchestrate collaborative architecture spike between PO, BA, and Architect agents |
| **Priority** | Must Have |
| **Dependencies** | FR-301 |
**Acceptance Criteria:**
- [ ] AC-302.1: Spike triggered after requirements approval
- [ ] AC-302.2: PO, BA, and Architect collaborate on technical approach
- [ ] AC-302.3: Tech stack recommendations generated with rationale
- [ ] AC-302.4: Architecture Decision Records (ADRs) created
- [ ] AC-302.5: Risk assessment and mitigation strategies documented
- [ ] AC-302.6: Client approves tech stack and team composition
#### FR-303: Sprint Planning Workflow
| Attribute | Value |
|-----------|-------|
| **ID** | FR-303 |
| **Title** | Sprint Planning Workflow |
| **Description** | System shall automate sprint planning with backlog grooming, estimation, and capacity planning |
| **Priority** | Must Have |
| **Dependencies** | FR-302, FR-401 |
**Acceptance Criteria:**
- [ ] AC-303.1: PM agent creates sprint backlog from prioritized stories
- [ ] AC-303.2: Story point estimation using historical data
- [ ] AC-303.3: Capacity planning based on available agents
- [ ] AC-303.4: Dependencies identified and sequenced
- [ ] AC-303.5: Sprint goal defined and communicated
- [ ] AC-303.6: Sprint plan presented for client approval (if required by autonomy level)
#### FR-304: Implementation Workflow
| Attribute | Value |
|-----------|-------|
| **ID** | FR-304 |
| **Title** | Implementation Workflow |
| **Description** | System shall orchestrate autonomous implementation with appropriate checkpoints |
| **Priority** | Must Have |
| **Dependencies** | FR-303 |
**Acceptance Criteria:**
- [ ] AC-304.1: Engineer agents pick up stories from sprint backlog
- [ ] AC-304.2: Feature branches created automatically
- [ ] AC-304.3: Code implementation with unit tests
- [ ] AC-304.4: Code review by peer Engineer agent
- [ ] AC-304.5: QA agent performs testing
- [ ] AC-304.6: PR created and merged upon approval
- [ ] AC-304.7: Progress updates visible in real-time
#### FR-305: Sprint Demo Workflow
| Attribute | Value |
|-----------|-------|
| **ID** | FR-305 |
| **Title** | Sprint Demo Workflow |
| **Description** | System shall generate sprint demo materials and facilitate client review |
| **Priority** | Should Have |
| **Dependencies** | FR-304 |
**Acceptance Criteria:**
- [ ] AC-305.1: Demo summary document generated
- [ ] AC-305.2: Completed stories listed with screenshots/recordings
- [ ] AC-305.3: Metrics presented (velocity, bug count, coverage)
- [ ] AC-305.4: Client feedback captured and converted to backlog items
- [ ] AC-305.5: Retrospective notes generated
- [ ] AC-305.6: Next sprint planning initiated
### 4.4 Issue Tracking (FR-400 Series)
#### FR-401: Issue Hierarchy
| Attribute | Value |
|-----------|-------|
| **ID** | FR-401 |
| **Title** | Issue Hierarchy (Epic/Story/Task) |
| **Description** | System shall support hierarchical issue structure with Epic, Story, and Task levels |
| **Priority** | Must Have |
| **Dependencies** | None |
**Acceptance Criteria:**
- [ ] AC-401.1: Epics contain multiple Stories
- [ ] AC-401.2: Stories contain multiple Tasks
- [ ] AC-401.3: Bidirectional navigation between levels
- [ ] AC-401.4: Status aggregation (Epic shows % complete based on Stories)
- [ ] AC-401.5: Epic/Story/Task templates available
- [ ] AC-401.6: Bulk operations on hierarchies
#### FR-402: External Issue Synchronization
| Attribute | Value |
|-----------|-------|
| **ID** | FR-402 |
| **Title** | External Issue Tracker Synchronization |
| **Description** | System shall mirror issues from external trackers while maintaining external tracker as source of truth |
| **Priority** | Must Have |
| **Dependencies** | FR-401, FR-802 |
**Acceptance Criteria:**
- [ ] AC-402.1: Issues synced from Gitea/GitHub/GitLab Issues
- [ ] AC-402.2: Local mirror maintains external tracker fields
- [ ] AC-402.3: `remote_url` stored for navigation to external tracker
- [ ] AC-402.4: `sync_status` tracks synchronization state
- [ ] AC-402.5: `last_synced_at` timestamp maintained
- [ ] AC-402.6: Changes in Syndarix pushed back to external tracker
- [ ] AC-402.7: Conflict resolution favors external tracker
- [ ] AC-402.8: Webhook-based real-time sync supported
#### FR-403: Issue CRUD Operations
| Attribute | Value |
|-----------|-------|
| **ID** | FR-403 |
| **Title** | Issue CRUD Operations |
| **Description** | System shall provide complete CRUD operations for issues with audit trail |
| **Priority** | Must Have |
| **Dependencies** | FR-401 |
**Acceptance Criteria:**
- [ ] AC-403.1: Create issues with title, description, type, priority
- [ ] AC-403.2: Read issues with filtering, sorting, search
- [ ] AC-403.3: Update issues with change tracking
- [ ] AC-403.4: Delete issues with soft delete and recovery
- [ ] AC-403.5: Assign issues to agent instances
- [ ] AC-403.6: Label and milestone management
- [ ] AC-403.7: Due date and estimation fields
- [ ] AC-403.8: Full audit trail for all changes
#### FR-404: Issue Comments and Activity
| Attribute | Value |
|-----------|-------|
| **ID** | FR-404 |
| **Title** | Issue Comments and Activity |
| **Description** | System shall track all issue activity including comments, status changes, and agent actions |
| **Priority** | Must Have |
| **Dependencies** | FR-403 |
**Acceptance Criteria:**
- [ ] AC-404.1: Comments support markdown formatting
- [ ] AC-404.2: Agent comments attributed to specific instance
- [ ] AC-404.3: Activity feed shows all changes chronologically
- [ ] AC-404.4: @mentions notify relevant agents or client
- [ ] AC-404.5: Comments synced with external tracker
- [ ] AC-404.6: File attachments supported in comments
### 4.5 Git Integration (FR-500 Series)
#### FR-501: Repository Management
| Attribute | Value |
|-----------|-------|
| **ID** | FR-501 |
| **Title** | Git Repository Management |
| **Description** | System shall manage Git repositories across supported providers (Gitea, GitHub, GitLab) |
| **Priority** | Must Have |
| **Dependencies** | FR-802 |
**Acceptance Criteria:**
- [ ] AC-501.1: Create new repositories on connected provider
- [ ] AC-501.2: Clone existing repositories for projects
- [ ] AC-501.3: Configure branch protection rules
- [ ] AC-501.4: Manage repository settings (description, visibility)
- [ ] AC-501.5: Support private and public repositories
- [ ] AC-501.6: Repository health monitoring
#### FR-502: Branch Management
| Attribute | Value |
|-----------|-------|
| **ID** | FR-502 |
| **Title** | Git Branch Management |
| **Description** | System shall automate branch creation, merging, and cleanup following GitFlow or trunk-based patterns |
| **Priority** | Must Have |
| **Dependencies** | FR-501 |
**Acceptance Criteria:**
- [ ] AC-502.1: Feature branches created automatically for stories
- [ ] AC-502.2: Branch naming convention enforced (e.g., `feature/STORY-123-description`)
- [ ] AC-502.3: Automatic rebasing on conflict-free merges
- [ ] AC-502.4: Branch cleanup after merge
- [ ] AC-502.5: Protected branch enforcement
- [ ] AC-502.6: GitFlow and trunk-based development supported
#### FR-503: Pull Request Management
| Attribute | Value |
|-----------|-------|
| **ID** | FR-503 |
| **Title** | Pull Request Management |
| **Description** | System shall create, review, and merge pull requests with automated workflows |
| **Priority** | Must Have |
| **Dependencies** | FR-502 |
**Acceptance Criteria:**
- [ ] AC-503.1: PR created automatically upon story completion
- [ ] AC-503.2: PR description generated from commit messages and story
- [ ] AC-503.3: Automated code review by Engineer agent
- [ ] AC-503.4: Review comments posted to PR
- [ ] AC-503.5: CI status integrated into merge decision
- [ ] AC-503.6: Squash merge with conventional commit message
- [ ] AC-503.7: PR linked to issue for traceability
#### FR-504: Commit Management
| Attribute | Value |
|-----------|-------|
| **ID** | FR-504 |
| **Title** | Commit Management |
| **Description** | System shall enforce commit conventions and maintain clean git history |
| **Priority** | Must Have |
| **Dependencies** | FR-502 |
**Acceptance Criteria:**
- [ ] AC-504.1: Conventional commit format enforced
- [ ] AC-504.2: Commit messages include issue reference
- [ ] AC-504.3: Atomic commits (one logical change per commit)
- [ ] AC-504.4: GPG signing supported
- [ ] AC-504.5: Commit author set to agent instance identity
- [ ] AC-504.6: Commit history viewable per story/feature
### 4.6 CI/CD Integration (FR-600 Series)
#### FR-601: Pipeline Configuration
| Attribute | Value |
|-----------|-------|
| **ID** | FR-601 |
| **Title** | CI/CD Pipeline Configuration |
| **Description** | System shall configure and manage CI/CD pipelines across supported providers |
| **Priority** | Must Have |
| **Dependencies** | FR-501, FR-803 |
**Acceptance Criteria:**
- [ ] AC-601.1: Pipeline templates for common tech stacks
- [ ] AC-601.2: Support for Gitea Actions, GitHub Actions, GitLab CI
- [ ] AC-601.3: Pipeline configuration generated by DevOps agent
- [ ] AC-601.4: Environment-specific configurations (dev, staging, prod)
- [ ] AC-601.5: Secret management integration
- [ ] AC-601.6: Manual approval gates supported
#### FR-602: Pipeline Execution Monitoring
| Attribute | Value |
|-----------|-------|
| **ID** | FR-602 |
| **Title** | Pipeline Execution Monitoring |
| **Description** | System shall monitor pipeline executions and surface results to agents |
| **Priority** | Must Have |
| **Dependencies** | FR-601 |
**Acceptance Criteria:**
- [ ] AC-602.1: Real-time pipeline status updates
- [ ] AC-602.2: Build logs accessible to agents
- [ ] AC-602.3: Test results parsed and displayed
- [ ] AC-602.4: Coverage reports integrated
- [ ] AC-602.5: Failure notifications trigger agent response
- [ ] AC-602.6: Deployment status tracking
### 4.7 Artifact Delivery (FR-700 Series)
#### FR-701: Code Artifact Delivery
| Attribute | Value |
|-----------|-------|
| **ID** | FR-701 |
| **Title** | Code Artifact Delivery |
| **Description** | System shall deliver complete source code with proper structure and documentation |
| **Priority** | Must Have |
| **Dependencies** | FR-501 |
**Acceptance Criteria:**
- [ ] AC-701.1: Full source code delivered via Git repository
- [ ] AC-701.2: README with setup instructions generated
- [ ] AC-701.3: Code follows agreed style guide
- [ ] AC-701.4: All dependencies documented (requirements.txt, package.json, etc.)
- [ ] AC-701.5: Environment configuration templates provided
- [ ] AC-701.6: Build and run scripts included
#### FR-702: Documentation Artifact Delivery
| Attribute | Value |
|-----------|-------|
| **ID** | FR-702 |
| **Title** | Documentation Artifact Delivery |
| **Description** | System shall deliver comprehensive documentation including technical docs, ADRs, and user guides |
| **Priority** | Must Have |
| **Dependencies** | FR-302 |
**Acceptance Criteria:**
- [ ] AC-702.1: Architecture Decision Records (ADRs) delivered
- [ ] AC-702.2: API documentation (OpenAPI/Swagger) generated
- [ ] AC-702.3: Data model documentation provided
- [ ] AC-702.4: Deployment guide included
- [ ] AC-702.5: User documentation generated (if applicable)
- [ ] AC-702.6: Changelog maintained and delivered
#### FR-703: Test Artifact Delivery
| Attribute | Value |
|-----------|-------|
| **ID** | FR-703 |
| **Title** | Test Artifact Delivery |
| **Description** | System shall deliver complete test suite with coverage reports |
| **Priority** | Must Have |
| **Dependencies** | FR-304 |
**Acceptance Criteria:**
- [ ] AC-703.1: Unit tests delivered with source code
- [ ] AC-703.2: Integration tests included
- [ ] AC-703.3: E2E tests provided (if applicable)
- [ ] AC-703.4: Test coverage report generated
- [ ] AC-703.5: Test documentation (how to run, what's covered)
- [ ] AC-703.6: Performance test results (if applicable)
### 4.8 Cost & Budget Management (FR-800 Series)
#### FR-801: Real-Time Cost Tracking
| Attribute | Value |
|-----------|-------|
| **ID** | FR-801 |
| **Title** | Real-Time Cost Tracking |
| **Description** | System shall track LLM API costs per agent, project, and sprint in real-time |
| **Priority** | Must Have |
| **Dependencies** | FR-102 |
**Acceptance Criteria:**
- [ ] AC-801.1: Token usage captured for every LLM call
- [ ] AC-801.2: Cost calculated using provider pricing
- [ ] AC-801.3: Cost attributed to agent, project, and sprint
- [ ] AC-801.4: Real-time cost dashboard updates via SSE
- [ ] AC-801.5: Historical cost data persisted for analytics
- [ ] AC-801.6: Cost breakdown by model type available
#### FR-802: Budget Configuration
| Attribute | Value |
|-----------|-------|
| **ID** | FR-802 |
| **Title** | Budget Configuration |
| **Description** | System shall support configurable budget limits per project with soft and hard enforcement |
| **Priority** | Must Have |
| **Dependencies** | FR-801 |
**Acceptance Criteria:**
- [ ] AC-802.1: Daily, weekly, and monthly budget limits configurable
- [ ] AC-802.2: Soft limits trigger alerts and model downgrades
- [ ] AC-802.3: Hard limits block LLM requests
- [ ] AC-802.4: Budget inheritance from organization to project
- [ ] AC-802.5: Budget override capability for administrators
#### FR-803: Budget Alerts
| Attribute | Value |
|-----------|-------|
| **ID** | FR-803 |
| **Title** | Budget Alerts |
| **Description** | System shall send notifications when budget thresholds are approached or exceeded |
| **Priority** | Should Have |
| **Dependencies** | FR-801, FR-802 |
**Acceptance Criteria:**
- [ ] AC-803.1: Configurable alert thresholds (e.g., 50%, 80%, 100%)
- [ ] AC-803.2: SSE notifications for real-time alerts
- [ ] AC-803.3: Email notifications for budget events
- [ ] AC-803.4: Alert history logged in audit trail
- [ ] AC-803.5: Auto-downgrade to cheaper models on soft limit
#### FR-804: Cost Analytics
| Attribute | Value |
|-----------|-------|
| **ID** | FR-804 |
| **Title** | Cost Analytics |
| **Description** | System shall provide cost analytics and optimization recommendations |
| **Priority** | Nice to Have |
| **Dependencies** | FR-801 |
**Acceptance Criteria:**
- [ ] AC-804.1: Cost trends visualization (daily, weekly, monthly)
- [ ] AC-804.2: Cost comparison across projects
- [ ] AC-804.3: Agent efficiency metrics (cost per task)
- [ ] AC-804.4: Model usage breakdown
- [ ] AC-804.5: Cost optimization recommendations
---
## 5. Non-Functional Requirements
### 5.1 Performance Requirements (NFR-100 Series)
#### NFR-101: Response Time
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-101 |
| **Description** | API response times under normal load |
| **Priority** | Must Have |
**Targets:**
- API endpoints: < 200ms (95th percentile)
- Agent message routing: < 500ms
- Search queries: < 1 second
- File uploads (< 10MB): < 5 seconds
- Dashboard load: < 2 seconds
#### NFR-102: Throughput
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-102 |
| **Description** | System throughput capacity |
| **Priority** | Must Have |
**Targets:**
- Concurrent active projects: 10+
- Concurrent active agents: 50+
- API requests per second: 100+
- WebSocket connections: 200+
- Background jobs per minute: 500+
#### NFR-103: Agent Response Time
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-103 |
| **Description** | AI agent response latency |
| **Priority** | Should Have |
**Targets:**
- Simple queries: < 10 seconds
- Code generation: < 60 seconds
- Complex analysis: < 120 seconds
- Failover to backup model: < 5 seconds
### 5.2 Scalability Requirements (NFR-200 Series)
#### NFR-201: Horizontal Scalability
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-201 |
| **Description** | System horizontal scaling capability |
| **Priority** | Should Have |
**Targets:**
- Web servers: Auto-scale 1-10 instances
- Worker processes: Auto-scale 2-20 instances
- Database: Read replicas supported
- Cache: Redis cluster supported
#### NFR-202: Data Scalability
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-202 |
| **Description** | Data growth handling |
| **Priority** | Must Have |
**Targets:**
- Projects: 1000+ per instance
- Issues: 100,000+ total
- Knowledge base documents: 10,000+ per project
- Conversation history: Unlimited with archival
- File storage: 1TB+ with object storage
### 5.3 Security Requirements (NFR-300 Series)
#### NFR-301: Authentication
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-301 |
| **Description** | Authentication mechanisms |
| **Priority** | Must Have |
**Requirements:**
- JWT-based authentication (access + refresh tokens)
- OAuth 2.0 provider mode for MCP integration
- Session management with device tracking
- Multi-factor authentication (future)
- SSO/SAML support (future)
#### NFR-302: Authorization
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-302 |
| **Description** | Authorization and access control |
| **Priority** | Must Have |
**Requirements:**
- Role-based access control (RBAC)
- Project-level permissions
- Resource ownership validation
- API key scoping for integrations
- Audit logging for all sensitive actions
#### NFR-303: Data Protection
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-303 |
| **Description** | Data encryption and protection |
| **Priority** | Must Have |
**Requirements:**
- TLS 1.3 for all communications
- Database encryption at rest
- Secrets management (never in code)
- PII handling compliance
- Data retention policies
#### NFR-304: API Security
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-304 |
| **Description** | API security measures |
| **Priority** | Must Have |
**Requirements:**
- Rate limiting (60/min default, 10/min for auth)
- CORS configuration
- CSRF protection
- Input validation
- SQL injection prevention
- Security headers (CSP, HSTS, X-Frame-Options)
### 5.4 Reliability Requirements (NFR-400 Series)
#### NFR-401: Availability
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-401 |
| **Description** | System availability targets |
| **Priority** | Must Have |
**Targets:**
- Uptime: 99.5% (monthly)
- Planned maintenance: < 4 hours/month
- Unplanned downtime: < 2 hours/month
- Recovery time objective (RTO): < 1 hour
- Recovery point objective (RPO): < 15 minutes
#### NFR-402: Fault Tolerance
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-402 |
| **Description** | Fault tolerance mechanisms |
| **Priority** | Must Have |
**Requirements:**
- Agent model failover on primary failure
- Database connection pooling with retry
- Message queue persistence
- Graceful degradation on external service failure
- Circuit breaker patterns for integrations
#### NFR-403: Data Durability
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-403 |
| **Description** | Data durability guarantees |
| **Priority** | Must Have |
**Requirements:**
- Database backups: Daily with 30-day retention
- Point-in-time recovery: 7 days
- Transaction logging: Enabled
- Replication: Synchronous for critical data
- Backup verification: Weekly automated tests
### 5.5 Usability Requirements (NFR-500 Series)
#### NFR-501: User Interface
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-501 |
| **Description** | User interface requirements |
| **Priority** | Should Have |
**Requirements:**
- Responsive design (desktop, tablet, mobile)
- Dark mode support
- Keyboard navigation
- Loading indicators for async operations
- Error messages are actionable
- Consistent design system (shadcn/ui)
#### NFR-502: Accessibility
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-502 |
| **Description** | Accessibility compliance |
| **Priority** | Should Have |
**Requirements:**
- WCAG 2.1 AA compliance
- Screen reader support
- Color contrast requirements
- Focus management
- Alt text for images
#### NFR-503: Internationalization
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-503 |
| **Description** | Multi-language support |
| **Priority** | Could Have |
**Requirements:**
- English (primary)
- Italian (inherited from PragmaStack)
- Locale-aware date/time/number formatting
- RTL support (future consideration)
### 5.6 Maintainability Requirements (NFR-600 Series)
#### NFR-601: Code Quality
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-601 |
| **Description** | Code quality standards |
| **Priority** | Must Have |
**Requirements:**
- Test coverage: > 80%
- Type coverage: 100% (TypeScript, Python type hints)
- Linting: Zero errors (ESLint, Ruff)
- Documentation: All public APIs documented
- Code review: Required for all changes
#### NFR-602: Logging and Monitoring
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-602 |
| **Description** | Observability requirements |
| **Priority** | Must Have |
**Requirements:**
- Structured logging (JSON format)
- Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
- Correlation IDs for request tracing
- Metrics collection (Prometheus format)
- Alerting on critical errors
#### NFR-603: Deployment
| Attribute | Value |
|-----------|-------|
| **ID** | NFR-603 |
| **Description** | Deployment requirements |
| **Priority** | Must Have |
**Requirements:**
- Docker containerization
- Docker Compose for local development
- Environment-based configuration
- Blue-green deployment support
- Rollback capability
- Database migration automation
---
## 6. System Architecture Overview
### 6.1 High-Level Architecture
```
+==============================================================================+
| CLIENT LAYER |
+==============================================================================+
| +-------------------+ +-------------------+ +-------------------+ |
| | Web Client | | Chat Interface | | Admin Console | |
| | (Next.js 16) | | (WebSocket/SSE) | | | |
| +-------------------+ +-------------------+ +-------------------+ |
+==============================================================================+
|
| HTTPS / WSS
v
+==============================================================================+
| API GATEWAY |
+==============================================================================+
| +-------------------+ +-------------------+ +-------------------+ |
| | Authentication | | Rate Limiting | | Load Balancer | |
| +-------------------+ +-------------------+ +-------------------+ |
+==============================================================================+
|
v
+==============================================================================+
| SYNDARIX CORE |
+==============================================================================+
| +------------------+ +------------------+ +------------------+ |
| | Agent | | Project | | Workflow | |
| | Orchestrator | | Manager | | Engine | |
| +------------------+ +------------------+ +------------------+ |
| | | | |
| +--------v--------------------v---------------------v--------+ |
| | FastAPI Backend | |
| | +------------+ +------------+ +------------+ | |
| | | API | | Services | | CRUD | | |
| | | Routes | | Layer | | Layer | | |
| | +------------+ +------------+ +------------+ | |
| +------------------------------------------------------------+ |
+==============================================================================+
|
v
+==============================================================================+
| MCP ORCHESTRATION LAYER |
| All integrations via unified MCP servers with project scoping |
+==============================================================================+
| +-------------+ +-------------+ +-------------+ +-------------+ |
| | LLM | | Git | | Knowledge | | File | |
| | Gateway | | MCP | | Base MCP | | System MCP | |
| +-------------+ +-------------+ +-------------+ +-------------+ |
| +-------------+ +-------------+ +-------------+ +-------------+ |
| | Code | | Issues | | CI/CD | | Search | |
| | Analysis MCP| | MCP | | MCP | | MCP | |
| +-------------+ +-------------+ +-------------+ +-------------+ |
+==============================================================================+
|
+---------------+---------------+
| | |
v v v
+===============+ +===============+ +===============================+
| PostgreSQL | | Redis | | External Services |
| + pgvector | | (Cache/Queue) | | (LLM APIs, Git, CI/CD, etc.) |
+===============+ +===============+ +===============================+
```
### 6.2 Component Details
#### 6.2.1 Agent Orchestrator
**Purpose:** Manages agent lifecycle, spawning, communication, and coordination
**Responsibilities:**
- Spawn agent instances from type definitions
- Route messages between agents
- Manage agent context and memory
- Handle agent failover
- Track agent resource usage
**Key Interfaces:**
```python
class AgentOrchestrator:
def spawn_agent(agent_type_id: UUID, project_id: UUID, name: str) -> AgentInstance
def terminate_agent(instance_id: UUID) -> None
def send_message(from_id: UUID, to_id: UUID, message: AgentMessage) -> None
def broadcast(from_id: UUID, target_type: AgentType, message: AgentMessage) -> None
def get_agent_status(instance_id: UUID) -> AgentStatus
```
#### 6.2.2 Project Manager (Component)
**Purpose:** Manages project lifecycle, configuration, and state
**Responsibilities:**
- Create and configure projects
- Track project status and progress
- Manage project settings and integrations
- Generate project reports
**Key Interfaces:**
```python
class ProjectManager:
def create_project(config: ProjectConfig) -> Project
def configure_project(project_id: UUID, settings: ProjectSettings) -> None
def get_project_status(project_id: UUID) -> ProjectStatus
def archive_project(project_id: UUID) -> None
```
#### 6.2.3 Workflow Engine
**Purpose:** Orchestrates multi-step workflows and agent collaboration
**Responsibilities:**
- Define and execute workflow templates
- Track workflow state and progress
- Handle workflow branching and conditions
- Manage approval gates
**Key Interfaces:**
```python
class WorkflowEngine:
def start_workflow(workflow_type: WorkflowType, project_id: UUID) -> WorkflowInstance
def advance_workflow(instance_id: UUID, input: WorkflowInput) -> WorkflowState
def pause_workflow(instance_id: UUID) -> None
def resume_workflow(instance_id: UUID) -> None
```
### 6.3 MCP Architecture
#### 6.3.1 Unified Singleton Pattern
**Decision:** ALL MCP servers are unified singletons with project_id/agent_id scoping. No per-project server spawning.
**Rationale:**
- Per-project servers too resource-heavy
- Unified servers enable cross-project learning
- Simpler deployment and management
- Consistent tool interface
**Implementation:**
```python
# All MCP tools accept explicit scope parameters
@mcp_tool
def search_knowledge(
project_id: str,
agent_id: str,
query: str,
scope: Literal["project", "global"] = "project"
) -> SearchResults:
"""Search knowledge base with explicit scoping"""
pass
@mcp_tool
def create_issue(
project_id: str,
agent_id: str,
title: str,
description: str,
issue_type: IssueType
) -> Issue:
"""Create issue in project-scoped context"""
pass
```
#### 6.3.2 MCP Server Registry
| MCP Server | Purpose | Scope Parameters |
|------------|---------|------------------|
| **LLM Gateway** | Route LLM requests with failover | agent_id, model_preference |
| **Git MCP** | Git operations | project_id, repo_id |
| **Knowledge Base MCP** | RAG and document search | project_id, agent_id |
| **File System MCP** | File operations | project_id, workspace_path |
| **Code Analysis MCP** | Static analysis, linting | project_id, file_path |
| **Issues MCP** | Issue tracking operations | project_id, issue_id |
| **CI/CD MCP** | Pipeline operations | project_id, pipeline_id |
| **Search MCP** | Full-text search | project_id, search_scope |
### 6.4 Data Flow Diagrams
#### 6.4.1 Requirements Discovery Flow
```
+--------+ 1. Describe Idea +----------+
| Client |----------------------->| PO |
+--------+ | Agent |
^ +----------+
| |
| 2. Clarifying
| Questions
| |
| 6. Approve v
| Requirements +----------+
| |Discovery |
+---------------------------|Workflow |
+----------+
|
3. Generate
Stories
|
v
+----------+
| BA |
| Agent |
+----------+
|
4. Detailed
Analysis
|
v
+----------+
|Requirements|
| Document |
+----------+
|
5. Present
to Client
|
v
+--------+
| Client |
+--------+
```
#### 6.4.2 Implementation Flow
```
+-------+ 1. Pick +----------+ 2. Create +----------+
|Sprint | Story |Engineer | Branch | Git |
|Backlog|------------->| Agent |--------------->| MCP |
+-------+ +----------+ +----------+
| |
3. Implement 4. Commit
| Changes
v |
+----------+ |
| Code |<---------------------+
+----------+
|
5. Create
PR
v
+----------+ 6. Review +----------+
| Git |--------------->| Engineer |
| MCP | | (Peer) |
+----------+ +----------+
| |
| 7. Approve
v |
+----------+ 8. Test +----------+
| QA |<---------------| Pipeline |
| Agent | | MCP |
+----------+ +----------+
|
9. Merge
|
v
+----------+
| Main |
| Branch |
+----------+
```
#### 6.4.3 Architecture Spike & Proposal Flow
```
+----------+ +----------+
|Approved | 1. Trigger Spike | PO |
|Require- |-------------------------->| Agent |
|ments | +----------+
+----------+ |
2. Summarize
Context
|
v
+----------+ 3. Requirements +---------------+
| BA |<---------------------| Spike Start |
| Agent | Handoff | Workflow |
+----------+ +---------------+
| |
4. Deep 5. Invite
Analysis Architect
| |
v v
+----------+ +----------+
| Domain | |Architect |
| Model | | Agent |
+----------+ +----------+
| |
+---------------+---------------------+
|
6. Collaborative
Brainstorm
|
v
+---------------+
| Tech Stack |
| Discussion |
+---------------+
|
7. Generate
Proposal
|
v
+---------------+
| Architecture |
| Proposal Doc |
+---------------+
|
8. Create ADRs
|
v
+---------------+
| ADRs |
| (Decisions) |
+---------------+
|
9. Present
to Client
|
v
+--------+ 10. Review +---------------+
| Client |<------------------| Approval |
+--------+ | Request |
| +---------------+
|
+-------------------+
| |
v v
+--------+ +--------+
|Approve | |Request |
+--------+ |Changes |
| +--------+
| |
v v
+----------+ +----------+
| Sprint | | Iterate |
| Planning | | Proposal |
+----------+ +----------+
|
+---> (Back to Step 6)
```
**Flow Description:**
1. **Trigger**: Requirements approval triggers architecture spike
2. **Context Summary**: PO summarizes client goals and constraints
3. **Requirements Handoff**: BA receives context for deep analysis
4. **Domain Analysis**: BA creates domain model and identifies technical needs
5. **Architect Involvement**: Architect agent invited to spike
6. **Collaborative Brainstorm**: PO, BA, and Architect discuss approaches
7. **Proposal Generation**: Architecture proposal document created
8. **ADR Creation**: Key decisions documented as ADRs
9. **Client Presentation**: Proposal presented with rationale
10. **Client Decision**: Approve or request changes (iterate if needed)
---
## 7. Data Requirements
### 7.1 Entity Definitions
#### 7.1.1 Core Entities
##### User
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| email | String(255) | Unique, Not Null | User email address |
| hashed_password | String(255) | Not Null | Bcrypt hashed password |
| full_name | String(100) | Nullable | Display name |
| is_active | Boolean | Default: true | Account status |
| is_superuser | Boolean | Default: false | Admin privileges |
| created_at | DateTime | Not Null | Creation timestamp |
| updated_at | DateTime | Nullable | Last update timestamp |
| deleted_at | DateTime | Nullable | Soft delete timestamp |
##### Project
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| name | String(100) | Not Null | Project name |
| description | Text | Nullable | Project description |
| complexity | Enum | Not Null | Script/Simple/Medium/Complex |
| status | Enum | Not Null | Active/Paused/Completed/Archived |
| autonomy_level | Enum | Not Null | FULL_CONTROL/MILESTONE/AUTONOMOUS |
| client_mode | Enum | Not Null | Technical/Auto |
| owner_id | UUID | FK -> User | Project owner |
| settings | JSONB | Not Null | Project configuration |
| created_at | DateTime | Not Null | Creation timestamp |
| updated_at | DateTime | Nullable | Last update timestamp |
##### AgentType
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| name | String(50) | Unique, Not Null | Type name |
| role | Enum | Not Null | PO/PM/BA/Architect/Engineer/etc. |
| base_model | String(100) | Not Null | Primary LLM model identifier |
| failover_model | String(100) | Nullable | Backup LLM model |
| expertise | String[] | Not Null | Expertise tags |
| personality | JSONB | Not Null | Personality configuration |
| capabilities | String[] | Not Null | Available capabilities |
| system_prompt | Text | Not Null | Base system prompt |
| is_active | Boolean | Default: true | Type availability |
| created_at | DateTime | Not Null | Creation timestamp |
| updated_at | DateTime | Nullable | Last update timestamp |
##### AgentInstance
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| name | String(50) | Not Null | Instance name (e.g., "Dave") |
| agent_type_id | UUID | FK -> AgentType | Parent type |
| project_id | UUID | FK -> Project | Assigned project |
| status | Enum | Not Null | Active/Idle/Terminated |
| context | JSONB | Not Null | Current context state |
| conversation_id | UUID | Nullable | Current conversation |
| rag_collection_id | String(100) | Nullable | Domain knowledge collection |
| token_usage | JSONB | Not Null | Token consumption stats |
| last_active_at | DateTime | Nullable | Last activity timestamp |
| created_at | DateTime | Not Null | Creation timestamp |
| terminated_at | DateTime | Nullable | Termination timestamp |
#### 7.1.2 Issue Tracking Entities
##### Issue
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| project_id | UUID | FK -> Project | Parent project |
| parent_id | UUID | FK -> Issue | Parent issue (for hierarchy) |
| type | Enum | Not Null | Epic/Story/Task/Bug |
| title | String(200) | Not Null | Issue title |
| description | Text | Nullable | Issue description (markdown) |
| status | Enum | Not Null | Open/InProgress/Review/Done/Closed |
| priority | Enum | Not Null | Critical/High/Medium/Low |
| story_points | Integer | Nullable | Estimation |
| assignee_id | UUID | FK -> AgentInstance | Assigned agent |
| reporter_id | UUID | FK -> User/AgentInstance | Creator |
| sprint_id | UUID | FK -> Sprint | Current sprint |
| milestone_id | UUID | FK -> Milestone | Target milestone |
| labels | String[] | Not Null | Issue labels |
| due_date | Date | Nullable | Due date |
| **external_tracker_type** | Enum | Nullable | Gitea/GitHub/GitLab |
| **external_issue_id** | String(100) | Nullable | External system ID |
| **external_issue_number** | Integer | Nullable | External issue number |
| **remote_url** | String(500) | Nullable | URL to external issue |
| **sync_status** | Enum | Not Null | Synced/Pending/Conflict/Error |
| **last_synced_at** | DateTime | Nullable | Last sync timestamp |
| created_at | DateTime | Not Null | Creation timestamp |
| updated_at | DateTime | Nullable | Last update timestamp |
| closed_at | DateTime | Nullable | Closure timestamp |
##### IssueComment
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| issue_id | UUID | FK -> Issue | Parent issue |
| author_id | UUID | FK -> User/AgentInstance | Comment author |
| author_type | Enum | Not Null | User/Agent |
| body | Text | Not Null | Comment content (markdown) |
| external_comment_id | String(100) | Nullable | External system ID |
| created_at | DateTime | Not Null | Creation timestamp |
| updated_at | DateTime | Nullable | Last update timestamp |
##### Sprint
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| project_id | UUID | FK -> Project | Parent project |
| name | String(100) | Not Null | Sprint name |
| goal | Text | Nullable | Sprint goal |
| number | Integer | Not Null | Sprint sequence number |
| status | Enum | Not Null | Planning/Active/Review/Completed |
| start_date | Date | Nullable | Sprint start |
| end_date | Date | Nullable | Sprint end |
| velocity | Integer | Nullable | Completed story points |
| created_at | DateTime | Not Null | Creation timestamp |
| completed_at | DateTime | Nullable | Completion timestamp |
#### 7.1.3 Git Integration Entities
##### Repository
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| project_id | UUID | FK -> Project | Parent project |
| provider | Enum | Not Null | Gitea/GitHub/GitLab |
| provider_repo_id | String(100) | Not Null | Provider's repository ID |
| name | String(100) | Not Null | Repository name |
| full_name | String(200) | Not Null | Owner/repo format |
| clone_url | String(500) | Not Null | HTTPS clone URL |
| ssh_url | String(500) | Nullable | SSH clone URL |
| default_branch | String(100) | Not Null | Default branch name |
| is_private | Boolean | Not Null | Visibility |
| created_at | DateTime | Not Null | Creation timestamp |
##### PullRequest
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| repository_id | UUID | FK -> Repository | Parent repository |
| provider_pr_id | String(100) | Not Null | Provider's PR ID |
| number | Integer | Not Null | PR number |
| title | String(200) | Not Null | PR title |
| description | Text | Nullable | PR description |
| status | Enum | Not Null | Open/Merged/Closed |
| source_branch | String(100) | Not Null | Source branch |
| target_branch | String(100) | Not Null | Target branch |
| author_id | UUID | FK -> AgentInstance | PR author |
| issue_id | UUID | FK -> Issue | Linked issue |
| remote_url | String(500) | Not Null | URL to PR |
| created_at | DateTime | Not Null | Creation timestamp |
| merged_at | DateTime | Nullable | Merge timestamp |
#### 7.1.4 Knowledge Base Entities
##### KnowledgeDocument
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| project_id | UUID | FK -> Project | Parent project (null for global) |
| collection_id | String(100) | Not Null | Vector store collection |
| title | String(200) | Not Null | Document title |
| content | Text | Not Null | Document content |
| content_type | Enum | Not Null | Markdown/Code/ADR/API/etc. |
| source_url | String(500) | Nullable | Original source |
| metadata | JSONB | Not Null | Additional metadata |
| embedding_id | String(100) | Not Null | Vector store ID |
| created_at | DateTime | Not Null | Creation timestamp |
| updated_at | DateTime | Nullable | Last update timestamp |
##### Conversation
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| project_id | UUID | FK -> Project | Parent project |
| participants | UUID[] | Not Null | Agent/User IDs |
| topic | String(200) | Nullable | Conversation topic |
| status | Enum | Not Null | Active/Archived |
| created_at | DateTime | Not Null | Creation timestamp |
| last_message_at | DateTime | Nullable | Last activity |
##### Message
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| conversation_id | UUID | FK -> Conversation | Parent conversation |
| sender_id | UUID | FK -> User/AgentInstance | Message sender |
| sender_type | Enum | Not Null | User/Agent |
| content | Text | Not Null | Message content |
| message_type | Enum | Not Null | Text/Code/Attachment/Action |
| metadata | JSONB | Not Null | Additional data |
| created_at | DateTime | Not Null | Creation timestamp |
### 7.2 Entity Relationship Diagram
```
+-------------+ +----------------+ +---------------+
| User |1-----*| Project |1-----*| Sprint |
+-------------+ +----------------+ +---------------+
|1 |1
| |
|* |*
+------+------+ +------+------+
| | | |
+------v------+ +----v----+ | +-----v-----+
|AgentInstance| |Repository| | | Issue |
+-------------+ +----------+ | +-----------+
|1 |1 | |1
| | | |
|* |* | |*
+------v------+ +----v----+ | +-----v-----+
| Message | | PR |----+ |IssueComment|
+-------------+ +---------+ +-----------+
^
|*
+------+------+
| Conversation|
+-------------+
^
|1
+------+------+
| Project |
+-------------+
```
### 7.3 Data Migration Strategy
1. **Schema Migrations:** Alembic with versioned migrations
2. **Data Migrations:** Separate migration scripts for data transformations
3. **Rollback Support:** Each migration includes downgrade path
4. **Zero-Downtime:** Migrations designed for online application
---
## 8. Integration Requirements
### 8.1 MCP Integration Architecture
All integrations follow the MCP-first pattern with unified singleton servers.
#### 8.1.1 LLM Gateway MCP
**Purpose:** Route LLM requests with model selection and failover
| Tool | Description | Parameters |
|------|-------------|------------|
| `chat_completion` | Generate chat completion | agent_id, messages, model_preference |
| `embedding` | Generate embeddings | text, model |
| `model_status` | Check model availability | model_id |
**Failover Logic:**
1. Attempt primary model (from agent type config)
2. On failure, switch to failover model
3. Log failover event for monitoring
4. Notify system admin on repeated failures
#### 8.1.2 Git MCP
**Purpose:** Git operations across providers (Gitea, GitHub, GitLab)
**Provider Priority:** Gitea first, then GitHub, then GitLab
| Tool | Description | Parameters |
|------|-------------|------------|
| `create_repository` | Create new repo | project_id, name, description, private |
| `clone_repository` | Clone existing repo | project_id, url |
| `create_branch` | Create feature branch | project_id, repo_id, branch_name, source |
| `commit_changes` | Commit file changes | project_id, repo_id, branch, files, message |
| `create_pr` | Create pull request | project_id, repo_id, source, target, title, body |
| `merge_pr` | Merge pull request | project_id, repo_id, pr_number, strategy |
| `get_diff` | Get branch diff | project_id, repo_id, base, head |
| `list_branches` | List repository branches | project_id, repo_id |
#### 8.1.3 Issues MCP
**Purpose:** Issue tracking operations with external sync
**Provider Priority:** Gitea Issues first, then GitHub Issues, then GitLab Issues
| Tool | Description | Parameters |
|------|-------------|------------|
| `create_issue` | Create new issue | project_id, title, body, type, priority |
| `update_issue` | Update issue fields | project_id, issue_id, fields |
| `add_comment` | Add issue comment | project_id, issue_id, body |
| `sync_from_external` | Pull external changes | project_id, issue_id |
| `push_to_external` | Push local changes | project_id, issue_id |
| `link_to_pr` | Link issue to PR | project_id, issue_id, pr_id |
#### 8.1.4 CI/CD MCP
**Purpose:** Pipeline configuration and monitoring
**Provider Priority:** Gitea Actions first, then GitHub Actions, then GitLab CI
| Tool | Description | Parameters |
|------|-------------|------------|
| `create_pipeline` | Create pipeline config | project_id, repo_id, template |
| `trigger_pipeline` | Start pipeline run | project_id, repo_id, branch |
| `get_pipeline_status` | Get run status | project_id, repo_id, run_id |
| `get_pipeline_logs` | Get execution logs | project_id, repo_id, run_id, job |
| `cancel_pipeline` | Cancel running pipeline | project_id, repo_id, run_id |
#### 8.1.5 Knowledge Base MCP
**Purpose:** RAG operations for agent context
| Tool | Description | Parameters |
|------|-------------|------------|
| `index_document` | Add document to KB | project_id, agent_id, content, metadata |
| `search_knowledge` | Semantic search | project_id, agent_id, query, scope, limit |
| `update_document` | Update indexed doc | project_id, document_id, content |
| `delete_document` | Remove from index | project_id, document_id |
| `list_collections` | List available collections | project_id |
#### 8.1.6 File System MCP
**Purpose:** Workspace file operations
| Tool | Description | Parameters |
|------|-------------|------------|
| `read_file` | Read file content | project_id, path |
| `write_file` | Write file content | project_id, path, content |
| `list_directory` | List directory contents | project_id, path |
| `create_directory` | Create directory | project_id, path |
| `delete_path` | Delete file/directory | project_id, path |
| `search_files` | Search by pattern | project_id, pattern, scope |
#### 8.1.7 Code Analysis MCP
**Purpose:** Static analysis and code intelligence
| Tool | Description | Parameters |
|------|-------------|------------|
| `analyze_file` | Static analysis | project_id, path |
| `lint_file` | Run linter | project_id, path, config |
| `format_file` | Auto-format | project_id, path |
| `get_symbols` | Extract symbols | project_id, path |
| `find_references` | Find symbol references | project_id, symbol |
| `get_complexity` | Calculate complexity | project_id, path |
### 8.2 External Service Integrations
#### 8.2.1 LLM Providers
| Provider | Models | Use Cases |
|----------|--------|-----------|
| **Anthropic** | Claude 3.5 Sonnet, Claude 3 Opus | Primary agents, complex reasoning |
| **OpenAI** | GPT-4, GPT-4 Turbo | Failover, specific tasks |
| **Local** | Llama 3, Mistral | Cost optimization, privacy |
#### 8.2.2 Git Providers
| Provider | Priority | Features |
|----------|----------|----------|
| **Gitea** | 1st | Self-hosted, full control |
| **GitHub** | 2nd | Popular, extensive ecosystem |
| **GitLab** | 3rd | DevOps integration |
#### 8.2.3 Authentication Providers
| Provider | Protocol | Use Case |
|----------|----------|----------|
| **Internal** | JWT | Primary authentication |
| **OAuth Provider** | OAuth 2.0 | MCP client authentication |
| **Google** | OAuth 2.0 | Social login (optional) |
| **GitHub** | OAuth 2.0 | Social login (optional) |
### 8.3 Integration Configuration
```yaml
# Example integration configuration
integrations:
llm:
primary:
provider: anthropic
model: claude-3-5-sonnet-20241022
api_key: ${ANTHROPIC_API_KEY}
failover:
provider: openai
model: gpt-4-turbo
api_key: ${OPENAI_API_KEY}
git:
provider: gitea
base_url: https://gitea.example.com
token: ${GITEA_TOKEN}
issues:
provider: gitea # Uses same provider as git
sync_interval: 60 # seconds
cicd:
provider: gitea_actions
# Inherits git provider config
mcp:
servers:
llm_gateway:
port: 9001
singleton: true
git_mcp:
port: 9002
singleton: true
issues_mcp:
port: 9003
singleton: true
knowledge_base_mcp:
port: 9004
singleton: true
file_system_mcp:
port: 9005
singleton: true
code_analysis_mcp:
port: 9006
singleton: true
cicd_mcp:
port: 9007
singleton: true
```
---
## 9. User Stories and Use Cases
### 9.1 Epic: Project Initialization
#### US-001: Create New Project (Technical Client)
**As a** technical client
**I want to** create a new project with detailed specifications
**So that** I can get exactly the software I need built
**Acceptance Criteria:**
- [ ] Can specify project name and description
- [ ] Can select complexity level manually
- [ ] Can configure tech stack preferences
- [ ] Can set autonomy level
- [ ] Can select Git provider and repository settings
- [ ] Can customize agent team composition
- [ ] Receive confirmation with project dashboard link
**Story Points:** 5
#### US-002: Create New Project (Auto Mode)
**As a** non-technical client
**I want to** describe my idea in plain language
**So that** AI agents can figure out the details
**Acceptance Criteria:**
- [ ] Can describe idea in natural language
- [ ] PO agent asks clarifying questions
- [ ] System suggests complexity and tech stack
- [ ] Can approve or request changes to suggestions
- [ ] Project created with recommended settings
**Story Points:** 8
### 9.2 Epic: Requirements Management
#### US-003: Define Requirements
**As a** client
**I want to** work with the PO agent to define requirements
**So that** the development team knows what to build
**Acceptance Criteria:**
- [ ] PO agent initiates discovery conversation
- [ ] Can describe features and goals
- [ ] PO generates user stories from conversation
- [ ] Can review and edit generated stories
- [ ] Can approve final requirements document
**Story Points:** 8
#### US-004: View Requirements Document
**As a** client
**I want to** view the generated requirements document
**So that** I can review what will be built
**Acceptance Criteria:**
- [ ] Document includes all user stories
- [ ] Each story has acceptance criteria
- [ ] Stories are prioritized
- [ ] Document exportable as PDF/Markdown
- [ ] Version history available
**Story Points:** 3
### 9.3 Epic: Development Workflow
#### US-005: Review Architecture Proposal
**As a** client
**I want to** review the architecture proposal
**So that** I can approve technical decisions
**Acceptance Criteria:**
- [ ] Proposal includes tech stack with rationale
- [ ] Architecture diagrams provided
- [ ] ADRs explain key decisions
- [ ] Risk assessment included
- [ ] Can approve, reject, or request changes
**Story Points:** 5
#### US-006: Monitor Sprint Progress
**As a** client
**I want to** monitor sprint progress in real-time
**So that** I know how the project is progressing
**Acceptance Criteria:**
- [ ] Dashboard shows current sprint status
- [ ] Burndown chart visible
- [ ] Completed stories listed
- [ ] In-progress work visible
- [ ] Blockers highlighted
- [ ] Agent activity feed available
**Story Points:** 5
#### US-007: Review Pull Request
**As a** client (FULL_CONTROL mode)
**I want to** review pull requests before merge
**So that** I can ensure code quality
**Acceptance Criteria:**
- [ ] PR notification received
- [ ] Can view code diff
- [ ] Agent review comments visible
- [ ] CI status displayed
- [ ] Can approve or request changes
- [ ] Can add comments
**Story Points:** 5
### 9.4 Epic: Issue Management
#### US-008: Create Issue Manually
**As a** client
**I want to** create issues manually
**So that** I can report bugs or request features
**Acceptance Criteria:**
- [ ] Can create Epic, Story, Task, or Bug
- [ ] Can set priority and labels
- [ ] Can assign to sprint
- [ ] Issue synced to external tracker
- [ ] Agent assigned automatically (optional)
**Story Points:** 3
#### US-009: View Issue Board
**As a** client
**I want to** view all issues on a kanban board
**So that** I can see project status at a glance
**Acceptance Criteria:**
- [ ] Columns for each status
- [ ] Drag-and-drop supported
- [ ] Filters by type, priority, assignee
- [ ] Search functionality
- [ ] Quick issue details on hover
**Story Points:** 5
### 9.5 Epic: Artifact Delivery
#### US-010: Receive Project Deliverables
**As a** client
**I want to** receive all project artifacts
**So that** I have everything needed to maintain the software
**Acceptance Criteria:**
- [ ] Source code in Git repository
- [ ] Documentation (README, API docs, ADRs)
- [ ] Test suite with coverage report
- [ ] Deployment configuration
- [ ] Changelog
- [ ] Download as ZIP option
**Story Points:** 5
### 9.6 Epic: Agent Management (Admin)
#### US-011: Configure Agent Type
**As an** administrator
**I want to** configure agent types
**So that** I can customize agent behavior
**Acceptance Criteria:**
- [ ] Can create new agent type
- [ ] Can set base and failover models
- [ ] Can define expertise areas
- [ ] Can configure personality
- [ ] Can set system prompt
- [ ] Can activate/deactivate types
**Story Points:** 8
#### US-012: Monitor Agent Health
**As an** administrator
**I want to** monitor agent health and performance
**So that** I can ensure system reliability
**Acceptance Criteria:**
- [ ] Dashboard shows all active agents
- [ ] Resource usage visible (tokens, API calls)
- [ ] Error rates displayed
- [ ] Failover events logged
- [ ] Alerts configurable
**Story Points:** 5
---
## 10. Acceptance Criteria
### 10.1 System-Level Acceptance Criteria
| ID | Criteria | Verification Method |
|----|----------|---------------------|
| SAC-001 | System creates project in < 30 seconds | Automated test |
| SAC-002 | Agent instances spawn in < 10 seconds | Automated test |
| SAC-003 | Issues sync with external tracker within 60 seconds | Integration test |
| SAC-004 | All API endpoints return < 200ms (95th percentile) | Load test |
| SAC-005 | System supports 10+ concurrent projects | Load test |
| SAC-006 | Agent failover occurs within 5 seconds | Chaos test |
| SAC-007 | All artifacts delivered on project completion | E2E test |
| SAC-008 | Audit trail complete for all sensitive actions | Security audit |
### 10.2 Feature-Level Acceptance Criteria
#### Project Management
| ID | Feature | Criteria |
|----|---------|----------|
| PAC-001 | Project Creation | Project created with all required fields |
| PAC-002 | Complexity Assessment | Correct complexity level assigned |
| PAC-003 | Autonomy Configuration | Correct approval requirements enforced |
| PAC-004 | Client Mode | Communication adapted to client proficiency |
#### Agent Management
| ID | Feature | Criteria |
|----|---------|----------|
| AAC-001 | Agent Spawning | Instance created with unique identity |
| AAC-002 | Agent Communication | Messages delivered and logged |
| AAC-003 | Agent RAG | Domain knowledge queries return relevant results |
| AAC-004 | Agent Failover | Backup model used on primary failure |
#### Issue Tracking
| ID | Feature | Criteria |
|----|---------|----------|
| IAC-001 | Issue Hierarchy | Parent-child relationships maintained |
| IAC-002 | External Sync | Changes reflected in external tracker |
| IAC-003 | Issue CRUD | All operations audited |
| IAC-004 | Comments | Synced with external tracker |
#### Git Integration
| ID | Feature | Criteria |
|----|---------|----------|
| GAC-001 | Repository Creation | Repo created on selected provider |
| GAC-002 | Branch Management | Branches follow naming convention |
| GAC-003 | PR Workflow | PRs linked to issues |
| GAC-004 | Merge Strategy | Commits follow conventional format |
---
## 11. Constraints and Assumptions
### 11.1 Technical Constraints
| ID | Constraint | Impact | Mitigation |
|----|------------|--------|------------|
| TC-001 | PostgreSQL 15+ required | Database compatibility | Document requirements |
| TC-002 | Python 3.11+ required | Backend deployment | Container images |
| TC-003 | Node.js 20+ required | Frontend deployment | Container images |
| TC-004 | LLM API rate limits | Agent throughput | Rate limiting, caching |
| TC-005 | MCP SDK compatibility | Integration options | Version pinning |
| TC-006 | pgvector extension required | Hosting requirements | Managed PostgreSQL |
### 11.2 Business Constraints
| ID | Constraint | Impact | Mitigation |
|----|------------|--------|------------|
| BC-001 | Internal tool only (v1) | No multi-tenant features | Design for future expansion |
| BC-002 | No SaaS deployment (v1) | Self-hosted only | Docker deployment |
| BC-003 | Limited to English (v1) | User base restriction | i18n infrastructure in place |
| BC-004 | Gitea priority | Provider flexibility | Abstraction layer |
### 11.3 Assumptions
| ID | Assumption | Risk if Invalid | Validation |
|----|------------|-----------------|------------|
| AS-001 | LLM APIs maintain current capabilities | Agent quality degradation | Continuous testing |
| AS-002 | Gitea API stable | Integration breakage | Version pinning, tests |
| AS-003 | Users have basic Git knowledge | Usability issues | Documentation, auto mode |
| AS-004 | Network connectivity to LLM providers | Service unavailability | Local model fallback |
| AS-005 | Docker available in deployment environment | Deployment complexity | Alternative deployment docs |
### 11.4 Dependencies
| ID | Dependency | Type | Owner | Risk |
|----|------------|------|-------|------|
| DP-001 | Anthropic API | External | Anthropic | Medium |
| DP-002 | OpenAI API (failover) | External | OpenAI | Low |
| DP-003 | Gitea Server | External | Self-hosted | Low |
| DP-004 | PostgreSQL | Infrastructure | Self-hosted | Low |
| DP-005 | Redis | Infrastructure | Self-hosted | Low |
| DP-006 | MCP SDK | Library | Anthropic | Medium |
---
## 12. Risks and Mitigations
### 12.1 Technical Risks
| ID | Risk | Probability | Impact | Mitigation |
|----|------|-------------|--------|------------|
| TR-001 | LLM API unavailability | Medium | High | Failover models, local fallback |
| TR-002 | Agent produces incorrect code | High | Medium | Peer review, automated testing |
| TR-003 | Knowledge base drift | Medium | Medium | Regular reindexing, validation |
| TR-004 | External sync conflicts | Medium | Low | Conflict resolution, manual override |
| TR-005 | Performance degradation at scale | Low | High | Load testing, optimization |
| TR-006 | Security vulnerabilities | Low | Critical | Security audits, penetration testing |
### 12.2 Business Risks
| ID | Risk | Probability | Impact | Mitigation |
|----|------|-------------|--------|------------|
| BR-001 | Users don't trust AI output | Medium | High | Transparency, review gates |
| BR-002 | Cost overruns from API usage | Medium | Medium | Usage monitoring, budgets |
| BR-003 | Adoption resistance | Low | High | Training, gradual rollout |
| BR-004 | Compliance requirements change | Low | Medium | Modular architecture |
### 12.3 Project Risks
| ID | Risk | Probability | Impact | Mitigation |
|----|------|-------------|--------|------------|
| PR-001 | Scope creep | High | Medium | Clear requirements, change control |
| PR-002 | Technical debt accumulation | Medium | Medium | Code reviews, refactoring sprints |
| PR-003 | Integration complexity | Medium | High | Spike investigations, POCs |
| PR-004 | Testing inadequacy | Low | High | Coverage requirements, E2E tests |
### 12.4 Risk Response Matrix
| Response | Actions |
|----------|---------|
| **Avoid** | Change approach to eliminate risk |
| **Mitigate** | Reduce probability or impact |
| **Transfer** | Shift risk to third party |
| **Accept** | Acknowledge and monitor |
---
## 13. Success Metrics
### 13.1 Key Performance Indicators (KPIs)
#### Delivery Metrics
| Metric | Target | Measurement |
|--------|--------|-------------|
| Project completion rate | > 90% | Projects completed / Projects started |
| Average delivery time | -50% vs manual | Time from start to completion |
| First-pass acceptance rate | > 85% | Deliverables accepted without rework |
| Bug escape rate | < 5% | Bugs found in production / Total bugs |
#### Quality Metrics
| Metric | Target | Measurement |
|--------|--------|-------------|
| Code coverage | > 80% | Automated test coverage |
| Documentation completeness | > 95% | Documented APIs / Total APIs |
| ADR compliance | 100% | Architecture decisions with ADRs |
| Security vulnerability density | < 1/1000 LOC | Vulnerabilities / Lines of code |
#### Efficiency Metrics
| Metric | Target | Measurement |
|--------|--------|-------------|
| Agent utilization | > 70% | Active time / Total time |
| Client intervention rate | < 20% (AUTONOMOUS) | Interventions / Total actions |
| Sprint velocity consistency | +/- 15% | Variance in completed points |
| Rework rate | < 10% | Reworked stories / Completed stories |
#### User Satisfaction Metrics
| Metric | Target | Measurement |
|--------|--------|-------------|
| Client satisfaction score | > 4.0/5.0 | Post-project survey |
| Feature adoption rate | > 80% | Users using feature / Total users |
| Time to first value | < 1 hour | Time to first useful output |
| Support ticket volume | < 5/project | Support requests per project |
### 13.2 Operational Metrics
| Metric | Target | Measurement |
|--------|--------|-------------|
| System uptime | > 99.5% | Uptime / Total time |
| API response time (p95) | < 200ms | 95th percentile latency |
| Error rate | < 0.1% | Errors / Total requests |
| Agent failover success rate | > 99% | Successful failovers / Failover attempts |
### 13.3 Business Metrics
| Metric | Target | Measurement |
|--------|--------|-------------|
| Cost per project | -30% vs traditional | Total cost / Projects delivered |
| Time to market | -50% vs traditional | Average delivery time |
| Resource efficiency | 3x improvement | Output / Human hours |
| ROI | > 300% (Year 1) | Value delivered / Investment |
---
## 14. Glossary
| Term | Definition |
|------|------------|
| **ADR** | Architecture Decision Record - A document capturing an important architectural decision with context, decision, and consequences |
| **Agent Instance** | A running instance of an agent type, assigned to a specific project with unique identity |
| **Agent Type** | A template definition for AI agents including model, expertise, and personality configuration |
| **Autonomy Level** | Configuration determining how much human approval is required for agent actions |
| **Backlog** | Prioritized list of work items (epics, stories, tasks) for a project |
| **Burndown Chart** | Visual representation of work remaining vs time in a sprint |
| **CI/CD** | Continuous Integration / Continuous Deployment - Automated build, test, and deploy pipelines |
| **Client Mode** | User proficiency setting (Technical or Auto) affecting communication style |
| **Complexity Level** | Project classification (Script/Simple/Medium/Complex) determining workflow |
| **Conventional Commit** | Standardized commit message format with type, scope, and description |
| **Epic** | Large body of work that can be broken down into smaller stories |
| **External Tracker** | Third-party issue tracking system (Gitea Issues, GitHub Issues, GitLab Issues) |
| **Failover Model** | Backup LLM model used when primary model is unavailable |
| **GitFlow** | Git branching model with feature, develop, release, and hotfix branches |
| **Issue Hierarchy** | Parent-child relationship between Epics, Stories, and Tasks |
| **MCP** | Model Context Protocol - Anthropic's protocol for LLM tool integration |
| **MoSCoW** | Prioritization method: Must Have, Should Have, Could Have, Won't Have |
| **pgvector** | PostgreSQL extension for vector similarity search (used for RAG) |
| **PR** | Pull Request - Code change proposal for review before merging |
| **PragmaStack** | Base template used for Syndarix (FastAPI + Next.js full-stack) |
| **RAG** | Retrieval-Augmented Generation - Enhancing LLM with external knowledge |
| **RBAC** | Role-Based Access Control - Authorization based on user roles |
| **Singleton MCP** | MCP server pattern where one server instance serves all projects |
| **Spike** | Time-boxed research activity to reduce technical uncertainty |
| **Sprint** | Fixed-length iteration (typically 1-2 weeks) for completing backlog items |
| **Story** | User-facing feature or capability described from user perspective |
| **Story Points** | Relative estimation unit for effort/complexity |
| **Sync Status** | State of synchronization between local and external issue tracker |
| **Task** | Technical work item, typically part of a story |
| **Velocity** | Measure of work completed per sprint (in story points) |
| **Workspace** | Isolated file system area for a project |
---
## Appendices
### Appendix A: Technology Stack Reference
| Layer | Technology | Version | Purpose |
|-------|------------|---------|---------|
| Backend Framework | FastAPI | 0.115+ | REST API, WebSocket |
| Backend Language | Python | 3.11+ | Server-side logic |
| Frontend Framework | Next.js | 16 | React application |
| Frontend Language | TypeScript | 5.0+ | Type-safe frontend |
| Database | PostgreSQL | 15+ | Primary data store |
| Vector Extension | pgvector | Latest | Embedding storage |
| Cache/Queue | Redis | 7.0+ | Caching, Celery broker |
| Task Queue | Celery | 5.3+ | Background jobs |
| ORM | SQLAlchemy | 2.0+ | Database operations |
| Validation | Pydantic | 2.0+ | Data validation |
| State Management | Zustand | 4.0+ | Frontend state |
| Data Fetching | TanStack Query | 5.0+ | API data caching |
| UI Components | shadcn/ui | Latest | Design system |
| CSS | Tailwind CSS | 4.0+ | Styling |
| Testing (Backend) | pytest | 8.0+ | Unit/integration tests |
| Testing (Frontend) | Jest | 29+ | Unit tests |
| Testing (E2E) | Playwright | 1.40+ | End-to-end tests |
| Containerization | Docker | 24+ | Deployment |
### Appendix B: API Endpoint Summary
| Category | Endpoint | Method | Description |
|----------|----------|--------|-------------|
| **Auth** | /api/v1/auth/login | POST | User authentication |
| | /api/v1/auth/refresh | POST | Token refresh |
| | /api/v1/auth/logout | POST | Session termination |
| **Projects** | /api/v1/projects | GET | List projects |
| | /api/v1/projects | POST | Create project |
| | /api/v1/projects/{id} | GET | Get project details |
| | /api/v1/projects/{id} | PATCH | Update project |
| | /api/v1/projects/{id} | DELETE | Archive project |
| **Agents** | /api/v1/agent-types | GET | List agent types |
| | /api/v1/agent-types | POST | Create agent type |
| | /api/v1/agents | GET | List agent instances |
| | /api/v1/agents/{id} | GET | Get instance details |
| | /api/v1/agents/{id}/messages | GET | Get agent messages |
| **Issues** | /api/v1/projects/{id}/issues | GET | List project issues |
| | /api/v1/projects/{id}/issues | POST | Create issue |
| | /api/v1/issues/{id} | GET | Get issue details |
| | /api/v1/issues/{id} | PATCH | Update issue |
| | /api/v1/issues/{id}/comments | GET | List comments |
| | /api/v1/issues/{id}/comments | POST | Add comment |
| **Sprints** | /api/v1/projects/{id}/sprints | GET | List sprints |
| | /api/v1/projects/{id}/sprints | POST | Create sprint |
| | /api/v1/sprints/{id} | GET | Get sprint details |
| **Git** | /api/v1/projects/{id}/repositories | GET | List repositories |
| | /api/v1/repositories/{id}/branches | GET | List branches |
| | /api/v1/repositories/{id}/prs | GET | List pull requests |
### Appendix C: Configuration Reference
```yaml
# syndarix.config.yaml
app:
name: Syndarix
environment: development # development | staging | production
debug: true
secret_key: ${SECRET_KEY}
database:
url: postgresql+asyncpg://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
pool_size: 20
max_overflow: 50
redis:
url: redis://${REDIS_HOST}:${REDIS_PORT}/0
llm:
providers:
anthropic:
api_key: ${ANTHROPIC_API_KEY}
models:
- claude-3-5-sonnet-20241022
- claude-3-opus-20240229
openai:
api_key: ${OPENAI_API_KEY}
models:
- gpt-4-turbo
- gpt-4
git:
default_provider: gitea
providers:
gitea:
base_url: ${GITEA_URL}
token: ${GITEA_TOKEN}
github:
token: ${GITHUB_TOKEN}
gitlab:
base_url: ${GITLAB_URL}
token: ${GITLAB_TOKEN}
mcp:
enabled: true
servers:
llm_gateway:
enabled: true
port: 9001
git:
enabled: true
port: 9002
issues:
enabled: true
port: 9003
knowledge_base:
enabled: true
port: 9004
file_system:
enabled: true
port: 9005
code_analysis:
enabled: true
port: 9006
cicd:
enabled: true
port: 9007
agents:
default_autonomy: MILESTONE
max_instances_per_type: 5
context_window: 100000
token_budget_per_project: 10000000
security:
jwt:
access_token_expire_minutes: 15
refresh_token_expire_days: 7
rate_limiting:
default: "60/minute"
auth: "10/minute"
cors:
allowed_origins:
- http://localhost:3000
```
### Appendix D: Open Questions
| ID | Question | Owner | Status | Resolution |
|----|----------|-------|--------|------------|
| OQ-001 | Maximum project size limits? | Architecture | Open | - |
| OQ-002 | Offline mode requirements? | Product | Open | - |
| OQ-003 | Audit log retention policy? | Security | Open | - |
| OQ-004 | Agent conversation export format? | Product | Open | - |
| OQ-005 | Custom MCP tool support? | Architecture | Open | - |
---
**Document Control**
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | 2024-12-01 | Product Team | Initial version |
| 2.0 | 2025-12-29 | Product Team | Comprehensive rewrite with all decisions incorporated |
---
*This document is the authoritative source of truth for Syndarix requirements. All implementation decisions should be validated against this document.*
Reference in New Issue View Git Blame Copy Permalink