forked from cardosofelipe/fast-next-template

Files

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

95 KiB

Raw Blame History

Syndarix Requirements Document

Version: 2.0 Last Updated: 2025-12-29 Status: Approved Document Owner: Product Team

Executive Summary
Problem Statement and Objectives
Stakeholder Analysis
Functional Requirements
Non-Functional Requirements
System Architecture Overview
Data Requirements
Integration Requirements
User Stories and Use Cases
Acceptance Criteria
Constraints and Assumptions
Risks and Mitigations
Success Metrics
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:

Context Switching Overhead: Developers constantly switch between tools, losing context and productivity
Knowledge Fragmentation: Project knowledge scattered across conversations, documents, and code
AI Babysitting: Current AI tools require constant human guidance and validation
Inconsistent Quality: No standardized process for AI-generated code review and testing
Missing Orchestration: No unified system to coordinate multiple AI capabilities
Limited Autonomy: Existing tools cannot handle end-to-end project delivery

2.2 Proposed Solution

Syndarix addresses these challenges through:

Structured Agency Model: Specialized AI agents with defined roles, expertise, and communication protocols
Unified Knowledge Base: Centralized, searchable repository with project and agent scoping
Autonomous Workflows: Agents work independently with checkpoints for human intervention
Quality Gates: Built-in review processes, testing requirements, and approval workflows
MCP Orchestration: Single integration layer for all external tools and services
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:

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:

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:

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:

# 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:

Trigger: Requirements approval triggers architecture spike
Context Summary: PO summarizes client goals and constraints
Requirements Handoff: BA receives context for deep analysis
Domain Analysis: BA creates domain model and identifies technical needs
Architect Involvement: Architect agent invited to spike
Collaborative Brainstorm: PO, BA, and Architect discuss approaches
Proposal Generation: Architecture proposal document created
ADR Creation: Key decisions documented as ADRs
Client Presentation: Proposal presented with rationale
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

Schema Migrations: Alembic with versioned migrations
Data Migrations: Separate migration scripts for data transformations
Rollback Support: Each migration includes downgrade path
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:

Attempt primary model (from agent type config)
On failure, switch to failover model
Log failover event for monitoring
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

# 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

# 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.

95 KiB Raw Blame History

Syndarix Requirements Document

Table of Contents

1. Executive Summary

1.1 Vision Statement

1.2 Key Objectives

1.3 Target Audience

1.4 Scope Summary

2. Problem Statement and Objectives

2.1 Problem Statement

2.2 Proposed Solution

2.3 Value Proposition

2.4 Business Objectives

3. Stakeholder Analysis

3.1 Human Stakeholders

3.1.1 Client (Human User)

3.1.2 System Administrator

3.2 AI Agent Stakeholders

3.2.1 Product Owner Agent

3.2.2 Project Manager Agent

3.2.3 Business Analyst Agent

3.2.4 Software Architect Agent

3.2.5 Software Engineer Agent

3.2.6 UI/UX Designer Agent

3.2.7 QA Engineer Agent

3.2.8 DevOps Engineer Agent

3.2.9 AI/ML Engineer Agent

3.2.10 Security Expert Agent

3.3 Agent Configuration Model

3.4 Stakeholder Communication Matrix

4. Functional Requirements

4.1 Agent Management (FR-100 Series)

FR-101: Agent Type Configuration

FR-102: Agent Instance Spawning

FR-103: Agent Domain Knowledge (RAG)

FR-104: Agent Communication

FR-105: Agent Monitoring

4.2 Project Management (FR-200 Series)

FR-201: Project Creation Wizard

FR-202: Project Configuration

FR-203: Autonomy Level Configuration

FR-204: Client Proficiency Modes

4.3 Workflow Management (FR-300 Series)

FR-301: Requirements Discovery Workflow

FR-302: Architecture Spike Workflow

FR-303: Sprint Planning Workflow

FR-304: Implementation Workflow

FR-305: Sprint Demo Workflow

4.4 Issue Tracking (FR-400 Series)

FR-401: Issue Hierarchy

FR-402: External Issue Synchronization

FR-403: Issue CRUD Operations

FR-404: Issue Comments and Activity

4.5 Git Integration (FR-500 Series)

FR-501: Repository Management

FR-502: Branch Management

FR-503: Pull Request Management

FR-504: Commit Management

4.6 CI/CD Integration (FR-600 Series)

FR-601: Pipeline Configuration

FR-602: Pipeline Execution Monitoring

4.7 Artifact Delivery (FR-700 Series)

FR-701: Code Artifact Delivery

FR-702: Documentation Artifact Delivery

FR-703: Test Artifact Delivery

4.8 Cost & Budget Management (FR-800 Series)

FR-801: Real-Time Cost Tracking

FR-802: Budget Configuration

FR-803: Budget Alerts

FR-804: Cost Analytics

5. Non-Functional Requirements

5.1 Performance Requirements (NFR-100 Series)

NFR-101: Response Time

NFR-102: Throughput

NFR-103: Agent Response Time

5.2 Scalability Requirements (NFR-200 Series)

NFR-201: Horizontal Scalability

NFR-202: Data Scalability

5.3 Security Requirements (NFR-300 Series)

NFR-301: Authentication

95 KiB

Raw Blame History