Multi-Agent Project Management with PiSovereign

How-To Guide: Plan an entire software project from requirements analysis through calendar milestones using 9 specialized AI agents — then execute the tasks with GitHub Copilot.

Overview
Prerequisites
Creating the Agent Team
Example Project: SmartInventory
Phase-by-Phase Walkthrough
Results: Calendar Events & Tasks
Executing Tasks with GitHub Copilot
Tips & Best Practices

Overview

PiSovereign enables a team of specialized agents to collaborate within a single AI conversation. Each agent has its own profile with a defined role, skills, communication style, and optional model overrides. The system automatically orchestrates agents in dependency-aware waves — executing tasks in parallel where possible and sequentially where necessary.

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                          USER (Chat UI)                           │
│  Project description + upload documents + @Agent mentions         │
└──────────────┬──────────────────────────────────────┬──────────────┘
               │                                      │
               ▼                                      ▼
┌──────────────────────────┐         ┌──────────────────────────────┐
│   File Ingestion Service │         │    Agentic Orchestrator      │
│  ┌────────────────────┐  │         │  ┌────────────────────────┐  │
│  │ Document Parser     │  │         │  │ 1. Planning (LLM)      │  │
│  │ OCR / Code Parser   │  │         │  │ 2. Validation          │  │
│  │ Entity Extraction   │  │         │  │ 3. Wave Computation    │  │
│  └────────┬───────────┘  │         │  │ 4. Parallel Execution  │  │
│           │              │         │  │ 5. Result Synthesis    │  │
│           ▼              │         │  └──────────┬─────────────┘  │
│  ┌────────────────────┐  │         │             │                │
│  │ Knowledge Graph     │◄─┼─────────┼─────────────┘                │
│  │ (Nodes + Edges +   │  │         │                              │
│  │  pgvector Embeddings)│  │         │  Sub-Agent Execution:       │
│  └────────────────────┘  │         │  ┌──────┐ ┌──────┐ ┌──────┐ │
└──────────────────────────┘         │  │ PM   │ │Resrch│ │Archi │ │
                                     │  └──┬───┘ └──┬───┘ └──┬───┘ │
                                     │     │        │        │     │
                                     │     ▼        ▼        ▼     │
                                     │  ┌──────────────────────┐   │
                                     │  │ Tool Execution       │   │
                                     │  │ (ReAct Loop)         │   │
                                     │  │ • create_calendar..  │   │
                                     │  │ • create_task        │   │
                                     │  │ • search_web         │   │
                                     │  │ • store_memory       │   │
                                     │  └──────────┬───────────┘   │
                                     └─────────────┼───────────────┘
                                                   │
                                                   ▼
                                     ┌──────────────────────────────┐
                                     │   CalDAV Server (Baikal)     │
                                     │  • VEVENT (Milestones)       │
                                     │  • VTODO  (Tasks w/ Priority)│
                                     └──────────────────────────────┘

The 9 Lifecycle Agents

#	Agent	Emoji	Primary Responsibility
1	PM / Orchestrator	📋	Milestones, timelines, coordination
2	Research	🔍	Knowledge graph analysis, refine requirements
3	Data / Analytics	📊	Data models, schema design, pattern detection
4	Solution Architect	🏗️	System architecture, interfaces, data flows
5	Security / DevSecOps	🔐	Auth, secrets, threat model, compliance
6	Developer	💻	Code planning, task decomposition, implementation
7	QA / Validation	✅	Test strategy, edge cases, validation
8	DevOps / SRE	🚀	CI/CD, deployment, monitoring, observability
9	Documentation	📝	ADRs, runbooks, calendar entries, knowledge

Dependency Flow

Phase 1: Intake (Upload documents)
    │
    ▼
Phase 2: PM/Orchestrator ──► High-level plan + milestones
    │
    ▼
Phase 3: Research ──► Requirements + knowledge graph
    │
    ├──────────────────┐
    ▼                  ▼
Phase 4: Data      Phase 5: Architect ◄──── Phase 6: Security
    │                  │                        │
    └──────┬───────────┘                        │
           ▼                                    │
Phase 7: Developer ◄───────────────────────────┘
    │
    ├──────────────────┐
    ▼                  ▼
Phase 8: QA        Phase 9: DevOps
    │                  │
    └──────┬───────────┘
           ▼
Phase 10: Documentation ──► Final tasks + calendar

Prerequisites

1. PiSovereign Docker Setup

PiSovereign must be running with the CalDAV profile enabled so that calendar events and tasks can be created:

# Start core + CalDAV
just docker-up -- --profile caldav

# Or start everything (incl. monitoring):
just docker-up-all

2. Configuration (`config.toml`)

The following sections must be enabled:

# ─── Agentic Mode ────────────────────────────────────────────
[agentic]
enabled = true
max_concurrent_sub_agents = 3          # Pi 5: 2-3, Desktop: 3-5
max_sub_agents_per_task = 8
total_timeout_minutes = 10
sub_agent_timeout_minutes = 5
require_approval_for = ["send_email", "delete_contact", "execute_code"]

# ─── Tool Calling (ReAct Loop) ───────────────────────────────
[agent.tool_calling]
enabled = true
max_iterations = 5
parallel_tool_execution = true

# ─── CalDAV Server ───────────────────────────────────────────
[caldav]
enabled = true
base_url = "http://baikal:80/dav.php"
# Credentials via Vault: just docker-vault-set-caldav USERNAME PASSWORD

# ─── Token Optimization (recommended) ───────────────────────
[token_optimization]
enabled = true
max_profile_prompt_tokens = 300        # Agent prompt budget

3. Vault Secrets

# Set CalDAV credentials
just docker-vault-set-caldav admin mysecurepassword

4. Verify Initial Setup

Open the web UI at http://localhost:3000 and navigate to:

Team (sidebar) → Manage agent profiles
Chat (sidebar) → Conversations with @mentions
Agentic (sidebar) → Launch complex multi-agent tasks

Creating the Agent Team

Create all 9 agents via the web UI (Team → + New Agent) or through the API. Below are the complete profile definitions for each agent.

1. PM / Orchestrator

POST /v1/agent-profiles
{
  "name": "PM",
  "role": "Senior project manager and orchestrator. Analyzes requirements, breaks down goals into milestones, creates timelines with calendar entries, assigns tasks to agents, and monitors progress.",
  "emoji": "📋",
  "skills": [
    "project_management", "milestone_planning", "task_decomposition",
    "risk_assessment", "stakeholder_communication", "resource_planning",
    "timeline_creation", "priority_management", "workflow_design",
    "multi_agent_coordination", "calendar_management"
  ],
  "style": {
    "tone": "structured and decisive",
    "verbosity": "normal",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are an experienced project manager. Your task is to break down requirements into clear milestones, create timelines with concrete calendar entries, and distribute tasks to specialized agents. Use the create_calendar_event and create_task tools to schedule deadlines and tasks in the calendar. Each milestone needs a date, a description, and clear deliverables. Prioritize by business value and technical dependencies.",
  "inference_overrides": {
    "temperature": 0.4
  },
  "autonomy_level": "high"
}

2. Research Agent

POST /v1/agent-profiles
{
  "name": "Research",
  "role": "Senior research agent. Analyzes internal documents, knowledge graphs, and external sources to refine requirements and close knowledge gaps.",
  "emoji": "🔍",
  "skills": [
    "document_analysis", "knowledge_graph_analysis", "requirements_refinement",
    "gap_analysis", "data_source_evaluation", "api_analysis",
    "constraint_identification", "fact_verification", "web_research",
    "data_quality_assessment"
  ],
  "style": {
    "tone": "analytical and thorough",
    "verbosity": "verbose",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a research specialist. Analyze the knowledge graph (via recall_memory) and search the web (via search_web) for relevant information. Identify knowledge gaps, verify assumptions, and clearly document open questions. Use store_memory to save key findings for other agents.",
  "inference_overrides": {
    "temperature": 0.5
  },
  "autonomy_level": "medium"
}

3. Data / Analytics Agent

POST /v1/agent-profiles
{
  "name": "DataAnalyst",
  "role": "Senior data analyst. Compares schemas, detects patterns in data, and proposes data models, transformation rules, and index strategies.",
  "emoji": "📊",
  "skills": [
    "data_modeling", "schema_design", "data_mapping", "data_validation",
    "pattern_recognition", "performance_analysis", "index_optimization",
    "data_quality", "data_transformation", "data_governance"
  ],
  "style": {
    "tone": "precise and data-driven",
    "verbosity": "normal",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a data analyst. Analyze existing data structures and propose optimal schemas, indexes, and data models. Consider performance, storage, and consistency. Use the knowledge graph to understand existing entities and their relationships. Document data flows clearly.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "medium"
}

4. Solution Architect Agent

POST /v1/agent-profiles
{
  "name": "Architect",
  "role": "Senior architect. Translates requirements into an overall technical architecture: services, interfaces, data flows, protocols, and deployment topology.",
  "emoji": "🏗️",
  "skills": [
    "system_architecture", "api_design", "data_flow_design",
    "microservices", "event_driven_architecture", "deployment_topology",
    "scalability_planning", "integration_patterns", "protocol_selection",
    "technology_evaluation"
  ],
  "style": {
    "tone": "technical and systematic",
    "verbosity": "verbose",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a solution architect. Design the overall technical architecture based on the results from research and data analysis. Define services, APIs, data flows, and deployment strategy. Document architecture decisions as ADRs (Architecture Decision Records). Focus on scalability, maintainability, and clean interfaces.",
  "inference_overrides": {
    "temperature": 0.4
  },
  "autonomy_level": "medium"
}

5. Security / DevSecOps Agent

POST /v1/agent-profiles
{
  "name": "Security",
  "role": "Senior security agent. Defines auth models, secrets management, encryption, logging policies, and analyzes threat models.",
  "emoji": "🔐",
  "skills": [
    "threat_modeling", "authentication_design", "authorization_design",
    "secrets_management", "encryption_strategy", "security_audit",
    "compliance_check", "owasp_analysis", "security_architecture",
    "incident_response_planning"
  ],
  "style": {
    "tone": "cautious and thorough",
    "verbosity": "verbose",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a security specialist. Analyze the planned architecture for vulnerabilities. Create a threat model, define auth flows (RBAC/ABAC), secrets management, and encryption strategies. Validate against OWASP Top 10. Deliver concrete security requirements as tasks.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "low"
}

6. Developer Agent

POST /v1/agent-profiles
{
  "name": "Developer",
  "role": "Senior developer. Writes production code, tests, configurations, and breaks down architecture decisions into actionable development tasks.",
  "emoji": "💻",
  "skills": [
    "code_generation", "code_review", "test_automation",
    "refactoring", "api_implementation", "database_migration",
    "module_design", "type_system_design", "dependency_management",
    "code_documentation"
  ],
  "style": {
    "tone": "pragmatic and concise",
    "verbosity": "terse",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a senior developer. Break down the architecture into concrete development tasks with clear acceptance criteria. Each task should describe a specific module, API route, or database migration. Prioritize by technical dependencies. Use create_task to register each task in the calendar.",
  "inference_overrides": {
    "temperature": 0.2
  },
  "autonomy_level": "medium"
}

7. QA / Validation Agent

POST /v1/agent-profiles
{
  "name": "QA",
  "role": "Senior QA agent. Plans and defines tests at all levels: unit, integration, contract, and end-to-end tests. Detects edge cases and validation gaps.",
  "emoji": "✅",
  "skills": [
    "test_planning", "test_design", "edge_case_detection",
    "test_coverage_analysis", "load_testing_strategy",
    "contract_testing", "regression_testing", "test_automation_strategy",
    "quality_metrics", "acceptance_criteria"
  ],
  "style": {
    "tone": "meticulous and systematic",
    "verbosity": "normal",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a QA specialist. Create a comprehensive test strategy based on the development tasks. For each module, define: unit tests, integration tests, edge cases, and acceptance criteria. Identify risk areas that require special test coverage. Create QA tasks with create_task.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "medium"
}

8. DevOps / SRE Agent

POST /v1/agent-profiles
{
  "name": "DevOps",
  "role": "Senior DevOps and SRE agent. Defines CI/CD pipelines, deployment strategies, observability, and disaster recovery workflows.",
  "emoji": "🚀",
  "skills": [
    "ci_cd_pipeline_design", "deployment_strategy", "container_orchestration",
    "monitoring_setup", "log_analysis", "incident_response",
    "disaster_recovery", "infrastructure_as_code", "rollback_strategy",
    "performance_tuning"
  ],
  "style": {
    "tone": "operational and pragmatic",
    "verbosity": "normal",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a DevOps/SRE specialist. Define the CI/CD pipeline, container configuration, monitoring stack, and deployment strategy. Create concrete tasks for: pipeline setup, Docker configuration, monitoring alerts, and runbook creation. Use create_task for each DevOps task.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "medium"
}

9. Documentation / Knowledge Agent

POST /v1/agent-profiles
{
  "name": "Documentation",
  "role": "Senior documentation and knowledge agent. Creates ADRs, API documentation, runbooks, operational guides, and maintains the knowledge graph.",
  "emoji": "📝",
  "skills": [
    "technical_writing", "adr_creation", "api_documentation",
    "runbook_design", "onboarding_guides", "knowledge_management",
    "document_structuring", "version_tracking", "knowledge_graph_maintenance",
    "stakeholder_documentation"
  ],
  "style": {
    "tone": "clear and structured",
    "verbosity": "verbose",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a documentation specialist. Based on all prior results, create: ADRs, API documentation templates, operational guides, and a final project plan. Save key decisions to the knowledge graph (store_memory). Create final milestone events (create_calendar_event) and documentation tasks (create_task).",
  "inference_overrides": {
    "temperature": 0.4
  },
  "autonomy_level": "medium"
}

Tip: All agents can also be created visually via the web UI under Team — emoji, role, skills, and system prompt can be configured conveniently through the form interface.

Example Project: SmartInventory

As a running example throughout this guide, we use a fictitious mid-sized software project:

Project Description

SmartInventory is a cloud-native warehouse management system for mid-sized retail companies. The system manages stock levels in real time, supports barcode/QR code scanning via smartphone, automatically alerts on low inventory, integrates with supplier APIs for automated reorders, and provides a role-based dashboard for warehouse workers, procurement staff, and management.

Planned Technology Stack

Backend: Rust (Axum), PostgreSQL, Redis
Frontend: SolidJS + Tailwind CSS
Mobile: PWA with Camera API for barcode scanning
Deployment: Docker Compose, Traefik, Prometheus/Grafana
Authentication: OAuth 2.0 + RBAC

Documents for Intake

Over the course of this walkthrough, the following fictitious documents are “uploaded,” which the system ingests into the knowledge graph:

File	Contents
`requirements.md`	Functional & non-functional requirements
`data-model.csv`	Initial tables: products, warehouses, orders
`api-draft.json`	High-level REST API endpoint design
`stakeholder-interviews.md`	Summary of user interviews
`compliance-checklist.md`	GDPR and audit requirements

Phase-by-Phase Walkthrough

Phase 1: Project Intake — Uploading Documents

Goal: Load all project documents into the knowledge graph so that every agent can access them.

Step 1: Open Chat and Submit the Project Description

Open the Chat in the web UI and start a new conversation:

User:
I'm starting a new project called "SmartInventory" — a warehouse management system.
Here is the project description:

SmartInventory is a cloud-native warehouse management system for mid-sized retail
companies. It should manage stock levels in real time, support barcode scanning
via smartphone, alert on low inventory, integrate with supplier APIs for automated
reorders, and provide a role-based dashboard.

Tech stack: Rust (Axum), PostgreSQL, Redis, SolidJS, Docker Compose.
Target audience: Warehouse workers, procurement staff, management.
Planned go-live: Q3 2026.

Step 2: Upload Documents

In the chat input field: Click the file icon or drag and drop files into the input area.

User:
[Drag & Drop: requirements.md, data-model.csv, api-draft.json,
 stakeholder-interviews.md, compliance-checklist.md]

Here are the project documents. Please analyze them and integrate
the information into the knowledge graph.

What happens behind the scenes:

FileIngestionService receives each file
DocumentParser extracts the text (Markdown, CSV, JSON)
Entity Extraction identifies entities: Product, Warehouse, Order, Supplier, User Role, API Endpoint, GDPR, etc.
Knowledge Graph stores the entities as nodes with relationships:
- Product —[part_of]→ Warehouse
- Order —[relates_to]→ Supplier
- Dashboard —[used_by]→ Management
pgvector embeddings are generated for each entity → semantic search enabled

Expected response:

PiSovereign:
✅ 5 files processed:
  • requirements.md — 23 entities extracted
  • data-model.csv — 15 entities, 8 relationships
  • api-draft.json — 12 API endpoints identified
  • stakeholder-interviews.md — 9 stakeholder requirements
  • compliance-checklist.md — 7 compliance requirements

Knowledge graph updated: 66 nodes, 34 edges.
You can now use @PM to create the project plan.

Phase 2: PM / Orchestrator

Goal: High-level planning with milestones and a timeline as calendar entries.

Option A: @Mention in Chat

User:
@PM Create a project plan for SmartInventory with milestones and
concrete calendar entries. Planned start: April 1, 2026,
go-live: September 30, 2026.
Consider the uploaded requirements and data model.

Option B: Agentic Task (recommended for complex tasks)

Navigate to Agentic in the sidebar:

Task input:
Analyze the SmartInventory project (all uploaded documents in the
knowledge graph) and create a complete project plan:
1. Break the project into 5-8 milestones
2. Create a calendar entry for each milestone (create_calendar_event)
3. Create tasks for the main deliverables (create_task) with priorities
4. Consider technical dependencies and risks
5. Timeframe: April 1, 2026 – September 30, 2026

What the PM agent does (tool calls):

The PM agent uses the ReAct loop and invokes tools:

Tool Call 1: recall_memory("SmartInventory requirements data model")
→ Retrieves knowledge graph context: entities, relationships, stakeholders

Tool Call 2: create_calendar_event({
    "title": "M1: Project Kickoff & Setup",
    "start": "2026-04-01T09:00:00Z",
    "end": "2026-04-01T17:00:00Z",
    "description": "Kickoff, dev environment, repository, CI/CD scaffold"
})

Tool Call 3: create_calendar_event({
    "title": "M2: Data Model & API Design Review",
    "start": "2026-04-24T09:00:00Z",
    "end": "2026-04-24T17:00:00Z",
    "description": "Schema finalized, API spec reviewed, security audit passed"
})

Tool Call 4: create_task({
    "title": "Set up repository and CI/CD",
    "due_date": "2026-04-07",
    "priority": "high",
    "description": "Git repo, Docker Compose, GitHub Actions pipeline, linting & formatting"
})

... (additional tool calls for M3-M6 and associated tasks)

SSE events (live progress in the UI):

event: planning
data: {"summary": "6 milestones identified", "sub_tasks": 4}

event: sub_agent_spawned
data: {"label": "Milestone planning", "profile_name": "PM"}

event: step_completed
data: {"steps_completed": 1, "steps_total": 6, "current_step": "M1 created"}

event: task_completed
data: {"final_response": "Project plan created with 6 milestones...",
       "actual_duration_seconds": 45}

Result — Milestone Plan:

Milestone	Date	Deliverable
M1: Project Kickoff	Apr 1, 2026	Environment, repo, CI/CD
M2: Design Review	Apr 24, 2026	Schema, API spec, security audit
M3: Core Backend	May 22, 2026	CRUD APIs, auth, database access
M4: Frontend & PWA	Jun 19, 2026	Dashboard, barcode scanner, alerts
M5: Integrations	Jul 17, 2026	Supplier API, email notifications
M6: Go-Live	Sep 30, 2026	Production deployment, documentation

Phase 3: Research Agent

Goal: Refine requirements, identify knowledge gaps, research external sources.

User:
@Research Analyze the knowledge graph for SmartInventory and check:
1. Are all functional requirements complete?
2. Are there technical risks with the chosen stack?
3. Which barcode/QR standards must be supported?
4. Which supplier API standards (EDI, REST) are industry standard?
Research on the web and document findings.

What the Research agent does:

Tool Call 1: recall_memory("SmartInventory functional requirements")
→ Knowledge Graph: 23 functional requirements from requirements.md

Tool Call 2: search_web("barcode QR code standards warehouse management 2026")
→ Result: EAN-13, Code 128, QR Code (ISO 18004), GS1 DataMatrix

Tool Call 3: search_web("supplier API standards EDI REST integration warehouse")
→ Result: EDI X12, GS1 EANCOM, REST-based cXML, Punchout catalogs

Tool Call 4: store_memory("SmartInventory supports EAN-13, Code 128,
  QR Code (ISO 18004). Supplier integration via REST (cXML) and
  optional EDI X12. Open question: Multi-warehouse support not specified.")

Result report:

Research:
📋 Analysis complete. Key findings:

✅ Complete: 21/23 requirements are sufficiently specified
⚠️ Gaps identified:
  • Multi-warehouse support not defined (single or multiple warehouses?)
  • PWA offline capability not specified
  • Unit conversion (piece/carton/pallet) missing

🔍 Technical recommendations:
  • Barcode standards: EAN-13, Code 128, QR Code (ISO 18004)
  • Supplier API: REST with cXML preferred, EDI X12 as fallback
  • PWA camera: Web API MediaDevices + ZXing library

All findings stored in the knowledge graph.

Phase 4: Data / Analytics Agent

Goal: Finalize data model, schema design, index strategy.

User:
@DataAnalyst Analyze the existing data model from the knowledge graph
and create a final schema design for SmartInventory. Consider:
- The multi-warehouse requirement (from Research)
- Performance for real-time inventory queries
- Audit trail for compliance (GDPR)

Result:

DataAnalyst:
📊 Schema Design for SmartInventory:

Core Entities (PostgreSQL):
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  warehouses  │    │   products   │    │   suppliers  │
├──────────────┤    ├──────────────┤    ├──────────────┤
│ id (UUID)    │    │ id (UUID)    │    │ id (UUID)    │
│ name         │    │ sku          │    │ name         │
│ location     │◄───│ barcode      │    │ api_endpoint │
│ capacity     │    │ name         │───►│ api_type     │
│ is_active    │    │ unit         │    │ lead_time_d  │
└──────────────┘    │ min_stock    │    └──────────────┘
                    └──────────────┘
                           │
                    ┌──────┴────────┐
                    │   inventory   │
                    ├───────────────┤
                    │ product_id    │  ← Composite Index
                    │ warehouse_id  │  ← (product_id, warehouse_id)
                    │ quantity      │
                    │ last_counted  │
                    │ updated_at    │
                    └───────────────┘

Index Strategy:
  • B-Tree: products(sku), products(barcode), inventory(product_id, warehouse_id)
  • GIN: products(name) with pg_trgm for fuzzy search
  • Partitioning: audit_log by month (GDPR retention periods)

Audit Trail:
  • Table audit_log with JSONB payload
  • Triggers on inventory for INSERT/UPDATE/DELETE
  • Retention: 10 years (configurable)

Phase 5: Solution Architect Agent

Goal: Define system architecture, services, APIs, data flows.

User:
@Architect Design the overall architecture for SmartInventory based
on the data model and research findings. Define:
- Service boundaries and API design
- Event-driven processes (inventory alerts, reorder triggers)
- Deployment topology (Docker)
- Supplier integration interfaces

Result (abbreviated):

Architect:
🏗️ Architecture Design — SmartInventory

Services:
┌───────────────────────────────────────────────────────────┐
│                    Traefik (Reverse Proxy)                │
├──────────┬──────────┬──────────┬──────────┬──────────────┤
│ Auth     │ Inventory│ Supplier │ Alert    │ Dashboard    │
│ Service  │ Service  │ Gateway  │ Engine   │ (SolidJS)    │
│ (OAuth)  │ (CRUD+)  │ (cXML)  │ (Events) │ (PWA)        │
├──────────┴──────────┴──────────┴──────────┴──────────────┤
│              PostgreSQL        │         Redis            │
│           (Data + Audit)       │   (Cache + Pub/Sub)      │
└────────────────────────────────┴─────────────────────────┘

Event Flow (inventory alert):
  inventory.updated → Redis Pub/Sub → Alert Engine
  → IF quantity < min_stock → create_task("Review reorder")
  → Email to procurement team

ADR-001: Monorepo with service modules (no microservice split in V1)
ADR-002: Event-driven via Redis Pub/Sub (not Kafka — overhead too high)
ADR-003: OAuth 2.0 + RBAC with 3 roles: admin, buyer, warehouse_worker

Phase 6: Security / DevSecOps Agent

Goal: Threat model, auth design, compliance requirements.

User:
@Security Create a threat model for SmartInventory and define:
- Auth flow (OAuth 2.0 + RBAC)
- Secrets management strategy
- GDPR-compliant data processing
- API hardening (rate limiting, input validation)

Result (abbreviated):

Security:
🔐 Threat Model & Security Requirements

STRIDE Analysis:
  ┌─────────────┬───────────────────────┬──────────────┐
  │ Threat      │ Risk                  │ Mitigation   │
  ├─────────────┼───────────────────────┼──────────────┤
  │ Spoofing    │ Fake barcode scans    │ JWT + HMAC   │
  │ Tampering   │ Inventory manipulation│ Audit trail  │
  │ Repudiation │ Unauthorized orders   │ Audit log    │
  │ Info Disc.  │ Customer data leak    │ Encryption   │
  │ DoS         │ API flooding          │ Rate limit   │
  │ Elevation   │ Role escalation       │ RBAC + ABAC  │
  └─────────────┴───────────────────────┴──────────────┘

RBAC Roles:
  • admin: Full access + audit logs
  • buyer: Orders + suppliers
  • warehouse_worker: Inventory + scanner

Security tasks created:
  ☐ Implement OAuth 2.0 server (Priority: high)
  ☐ RBAC middleware (Priority: high)
  ☐ Configure API rate limiting (Priority: medium)
  ☐ Database encryption at rest (Priority: medium)
  ☐ GDPR: Deletion policy for personal data (Priority: high)

Phase 7: Developer Agent

Goal: Create concrete development tasks with acceptance criteria.

User:
@Developer Break down the architecture and security requirements into
concrete development tasks. Each task should be a clearly scoped
work package with:
- Title, description, acceptance criteria
- Priority and estimated effort
- Technical dependencies on other tasks
Create the tasks in the calendar.

Example tool calls from the Developer agent:

Tool Call: create_task({
    "title": "INV-001: Inventory CRUD API",
    "due_date": "2026-05-08",
    "priority": "high",
    "description": "REST endpoints for inventory:\n
      POST /api/v1/inventory (stock in)\n
      GET /api/v1/inventory?warehouse_id=X (inventory list)\n
      PATCH /api/v1/inventory/{id} (update stock)\n
      Acceptance Criteria:\n
      - Validate all inputs\n
      - Audit log for every change\n
      - Unit tests ≥ 90% coverage\n
      Depends on: Schema migration, Auth middleware"
})

Tool Call: create_task({
    "title": "INV-002: Barcode Scanner PWA Module",
    "due_date": "2026-06-05",
    "priority": "high",
    "description": "PWA camera module for barcode scanning:\n
      - MediaDevices API for camera access\n
      - ZXing-js for EAN-13, Code 128, QR\n
      - Offline queue: buffer scans locally\n
      Acceptance Criteria:\n
      - Recognition in < 500ms\n
      - Works without network (PWA offline)\n
      Depends on: INV-001 (API must be ready)"
})

Result: ~15-20 tasks in the calendar with correct dependency ordering.

Phase 8: QA / Validation Agent

Goal: Define test strategy and QA tasks.

User:
@QA Create a test strategy for SmartInventory based on the
developer tasks. Define:
- Unit test requirements per module
- Integration tests for API endpoints
- E2E tests for critical workflows (stock booking, reorder)
- Load tests (how many concurrent scanner sessions?)
Create QA tasks in the calendar.

Result (abbreviated):

QA:
✅ Test Strategy — SmartInventory

Test Pyramid:
  ┌─────────────────────┐
  │   E2E Tests (10)    │ ← Cypress/Playwright
  ├─────────────────────┤
  │  Integration (35)   │ ← API tests with Testcontainers
  ├─────────────────────┤
  │   Unit Tests (120+) │ ← Module tests + property tests
  └─────────────────────┘

Critical Paths (E2E):
  1. Login → Dashboard → Inventory overview
  2. Open scanner → Scan barcode → Inventory updated
  3. Stock below minimum → Alert → Reorder triggered
  4. Supplier API timeout → Fallback → Manual notification

Load Test Targets:
  • 50 concurrent scanner sessions
  • 1,000 inventory queries/minute
  • 99.9% availability under load

QA tasks created: 8 tasks with priorities in the calendar.

Phase 9: DevOps / SRE Agent

Goal: Define CI/CD, deployment, and monitoring.

User:
@DevOps Define the CI/CD pipeline and deployment strategy for
SmartInventory. Consider:
- GitHub Actions as CI/CD
- Docker Compose for staging/production
- Prometheus + Grafana for monitoring
- Rollback strategy
Create DevOps tasks in the calendar.

Result (abbreviated):

DevOps:
🚀 CI/CD & Deployment Strategy

Pipeline Stages:
  ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐
  │ Lint │──►│Build │──►│ Test │──►│Stage │──►│ Prod │
  │      │   │Docker│   │Unit+ │   │Deploy│   │Deploy│
  │      │   │Image │   │Integr│   │ + E2E│   │Blue/ │
  │      │   │      │   │      │   │      │   │Green │
  └──────┘   └──────┘   └──────┘   └──────┘   └──────┘

Monitoring Alerts:
  • inventory_low_stock_total > threshold → PagerDuty
  • http_request_duration_p99 > 500ms → Slack
  • error_rate_5xx > 1% → PagerDuty

DevOps tasks created: 6 tasks in the calendar
  ☐ GitHub Actions pipeline (Priority: high, due Apr 7)
  ☐ Docker Compose production config (Priority: high, due Apr 14)
  ☐ Prometheus + Grafana setup (Priority: medium, due May 1)
  ☐ Define alerting rules (Priority: medium, due May 15)
  ☐ Blue/green deployment script (Priority: medium, due Jul 1)
  ☐ Disaster recovery runbook (Priority: low, due Sep 1)

Phase 10: Documentation / Knowledge Agent

Goal: Consolidate final documentation, ADRs, and calendar milestones.

User:
@Documentation Create the final project documentation for SmartInventory:
1. Summarize all architecture decisions as ADRs
2. Create an API documentation template
3. Write an onboarding document for new developers
4. Create final milestone calendar entries with review dates
5. Store all findings in the knowledge graph

Tool calls from the Documentation agent:

Tool Call: store_memory("SmartInventory ADR-001: Monorepo with service modules
  instead of microservices. Rationale: Team size (3-5 devs), reduced ops overhead,
  easier debugging. Trade-off: Later migration to microservices possible.")

Tool Call: store_memory("SmartInventory ADR-002: Redis Pub/Sub instead of Kafka.
  Rationale: Lower infrastructure complexity, sufficient for ~1,000 events/min.
  Trade-off: No replay capability, acceptable for V1.")

Tool Call: create_calendar_event({
    "title": "SmartInventory: M2 Design Review",
    "start": "2026-04-24T10:00:00Z",
    "end": "2026-04-24T12:00:00Z",
    "description": "Review: Data model, API spec, security audit.\n
      Participants: Architect, Security, DataAnalyst.\n
      Deliverables: Final schema, API OpenAPI spec, threat model.",
    "location": "Remote / Video Call"
})

Tool Call: create_calendar_event({
    "title": "SmartInventory: M4 Frontend Review",
    "start": "2026-06-19T10:00:00Z",
    "end": "2026-06-19T12:00:00Z",
    "description": "Review: Dashboard, PWA scanner, responsive design.\n
      Deliverables: Working prototype, accessibility audit.",
    "location": "Remote / Video Call"
})

Tool Call: create_task({
    "title": "DOC-001: API Documentation (OpenAPI 3.1)",
    "due_date": "2026-05-15",
    "priority": "medium",
    "description": "Complete OpenAPI spec for all endpoints.\n
      Must include: Schemas, examples, auth flows, error codes."
})

Results: Calendar Entries & Tasks

After completing all 10 phases, the following entries exist in the CalDAV server (Baikal):

Milestone Calendar (VEVENT)

Date	Milestone	Status
Apr 1, 2026	M1: Project Kickoff & Setup	Kick-off
Apr 24, 2026	M2: Design Review	Schema, API, Security
May 22, 2026	M3: Core Backend complete	CRUD, Auth, DB
Jun 19, 2026	M4: Frontend & PWA Review	Dashboard, Scanner
Jul 17, 2026	M5: Integrations complete	Suppliers, Alerts
Sep 4, 2026	M6: Pre-Launch Review	Load tests, Staging
Sep 30, 2026	M7: Go-Live	Production deployment

Task Board (VTODO)

All tasks are created as VTODO entries in CalDAV, with:

Priority: High (1–3) / Medium (4–6) / Low (7–9)
Status: NEEDS-ACTION → IN-PROGRESS → COMPLETED
Categories: backend, frontend, devops, security, qa, docs
Dependencies: via RELATED-TO (parent ID) in the VTODO

Example VTODO:
BEGIN:VTODO
UID:inv-001-inventory-crud@smartinventory
SUMMARY:INV-001: Inventory CRUD API
DESCRIPTION:REST endpoints for inventory...
DUE;VALUE=DATE:20260508
PRIORITY:3
STATUS:NEEDS-ACTION
CATEGORIES:backend,api
RELATED-TO:inv-000-schema-migration
END:VTODO

Task Overview by Phase

April 2026
├── CW 14: Repository setup, CI/CD pipeline                   [DevOps]
├── CW 15: Schema migration, auth middleware                   [Dev, Security]
├── CW 16: Finalize API design                                 [Architect]
└── CW 17: Design Review (M2) ⭐                               [All]

May 2026
├── CW 18: Inventory CRUD API                                  [Dev]
├── CW 19: Product management, warehouse management            [Dev]
├── CW 20: Unit tests + integration tests (core)               [QA]
├── CW 21: API documentation, monitoring setup                 [Docs, DevOps]
└── CW 22: Core Backend Review (M3) ⭐                          [All]

June 2026
├── CW 23: Dashboard (SolidJS), responsive layout              [Dev]
├── CW 24: Barcode scanner PWA module                          [Dev]
├── CW 25: Frontend tests, accessibility audit                 [QA]
└── CW 26: Frontend Review (M4) ⭐                              [All]

July 2026
├── CW 27: Supplier gateway (cXML)                             [Dev]
├── CW 28: Alert engine (Redis Pub/Sub)                        [Dev]
├── CW 29: Integration tests, contract tests                   [QA]
└── CW 30: Integrations Review (M5) ⭐                          [All]

August 2026
├── CW 31-32: Load tests, performance optimization             [QA, DevOps]
├── CW 33: Blue/green deployment, staging                      [DevOps]
├── CW 34: Penetration test, security audit                    [Security]
└── CW 35: GDPR checklist, runbooks                            [Docs, Security]

September 2026
├── CW 36: Pre-Launch Review (M6) ⭐                             [All]
├── CW 37-38: Bug fixes, finalize documentation                [Dev, Docs]
├── CW 39: Go-Live preparation                                 [DevOps]
└── CW 40: Go-Live (M7) 🚀                                      [All]

Tips & Best Practices

1. Preserve Conversation Context

Keep all phases in the same conversation. PiSovereign merges messages from all agents — allowing @Architect to access the results of @Research without re-entering information.

# Bad: New conversation per agent
Chat 1: @Research → Results are lost
Chat 2: @Architect → has no context

# Good: Everything in one conversation
Chat 1: Upload → @Research → @DataAnalyst → @Architect → ...
         └── All agents see the entire history

2. Use Agentic Tasks for Complex Phases

For phases with multiple parallel subtasks (e.g., PM planning), Agentic Mode is more efficient than individual @Mentions because it:

Automatically splits subtasks into parallel waves
Respects dependencies
Shows live progress via SSE
Consolidates results from all sub-agents at the end

3. Actively Leverage the Knowledge Graph

The knowledge graph is the project’s “memory”. Use it deliberately:

Intake: Upload documents → Entities are automatically extracted
Query: Agents use recall_memory automatically for RAG context
Store: Agents use store_memory for important decisions
API: GET /v1/knowledge-graph/stats shows graph statistics

4. Agent Memory for Continuity

Each agent has its own long-term memory (AgentMemory) that persists across tasks. The PM agent “remembers” the last project status, and the Security agent remembers previously identified risks.

5. Token Optimization for Large Projects

When a conversation accumulates many messages, automatic token optimization kicks in:

Rolling Summary: Old messages are condensed into summaries
Progressive Tool Compression: Previously used tools are compressed
Context Budget: System prompt, RAG, and history share the context window

Configurable via [token_optimization] in config.toml.

6. Approval Workflows for Critical Actions

Certain tools require user approval before execution (configured in [agentic] require_approval_for):

require_approval_for = ["send_email", "delete_contact", "execute_code"]

For these actions, the agent pauses and waits for your confirmation.

7. Version Agent Profiles

Every profile update creates a new version. Use version tags to mark proven configurations:

POST /v1/agent-profiles/{id}/versions/{version}/tag
{ "tag": "smartinventory-v1" }

This lets you reproduce agent configurations after a project concludes.

8. Maximize Parallel Agent Work

The orchestrator distributes independent subtasks across parallel waves. To make optimal use of this:

Formulate tasks with clear dependencies
Independent tasks (e.g., Security + Architect) can run in parallel
max_concurrent_sub_agents = 3 is optimal for Raspberry Pi 5
On desktop hardware: up to 5 parallel agents

Executing Tasks with GitHub Copilot

Once PiSovereign’s agents have created milestones and tasks, you can feed them to GitHub Copilot (in VS Code Agent Mode) for automated implementation. The recommended workflow uses the REST API to query tasks per milestone in dependency order, then generates a structured prompt file that Copilot can execute step by step.

API vs. Export — Which Approach Is Better?

Approach	Pros	Cons
API query (recommended)	Always up to date, filterable, includes status	Requires PiSovereign to be running
Markdown export (via script)	Works offline, version-controllable in Git	Snapshot — can become stale
iCal export (CalDAV native)	Standards-based, importable into other tools	Not human-readable, no Copilot integration

Recommendation: Use the API query → Markdown export pipeline. Query tasks live via the API, then export a Markdown file that serves as Copilot’s work instruction. This combines freshness with offline usability.

Step 1: Query Milestones and Linked Tasks

PiSovereign links tasks to milestone events via the Event-Task Link API. Query milestones (calendar events) and their associated tasks:

# List all milestone events in a date range
curl -s http://localhost:3000/v1/calendar/events?start=2026-04-01&end=2026-09-30 \
  | jq '.events[] | {id, title, start, end, description}'

# Get tasks linked to a specific milestone
curl -s http://localhost:3000/v1/calendar/events/{event_id}/tasks \
  | jq '.tasks[] | {id, title, priority, status, due_date, description}'

# List all tasks, filtered by status and priority
curl -s "http://localhost:3000/v1/tasks?status=pending&priority=high" \
  | jq '.tasks[]'

# Get the dependency order for a task list
curl -s http://localhost:3000/v1/tasks/lists/{list_id}/order \
  | jq '.order'

Step 2: Export Tasks as Copilot Work Instructions

Use this shell script to generate a structured Markdown file from the API that GitHub Copilot can process as a task list:

#!/usr/bin/env bash
# export-tasks-for-copilot.sh
# Exports PiSovereign tasks per milestone as a Copilot-ready Markdown file.

set -euo pipefail

API="http://localhost:3000"
OUTPUT="copilot-tasks.md"
START_DATE="${1:-2026-04-01}"
END_DATE="${2:-2026-09-30}"

echo "# Project Tasks for GitHub Copilot" > "$OUTPUT"
echo "" >> "$OUTPUT"
echo "> Auto-generated from PiSovereign on $(date -Iseconds)" >> "$OUTPUT"
echo "> Execute tasks in the listed order per milestone." >> "$OUTPUT"
echo "" >> "$OUTPUT"

# Fetch milestones sorted by date
MILESTONES=$(curl -s "${API}/v1/calendar/events?start=${START_DATE}&end=${END_DATE}")

echo "$MILESTONES" | jq -r '.events | sort_by(.start)[] | @base64' | while read -r EVENT; do
  TITLE=$(echo "$EVENT" | base64 -d | jq -r '.title')
  EVENT_ID=$(echo "$EVENT" | base64 -d | jq -r '.id')
  DATE=$(echo "$EVENT" | base64 -d | jq -r '.start[:10]')
  DESC=$(echo "$EVENT" | base64 -d | jq -r '.description // ""')

  echo "## ${TITLE}" >> "$OUTPUT"
  echo "**Deadline**: ${DATE}" >> "$OUTPUT"
  [ -n "$DESC" ] && echo "" >> "$OUTPUT" && echo "${DESC}" >> "$OUTPUT"
  echo "" >> "$OUTPUT"

  # Fetch linked tasks for this milestone
  TASKS=$(curl -s "${API}/v1/calendar/events/${EVENT_ID}/tasks")
  TASK_COUNT=$(echo "$TASKS" | jq '.tasks | length')

  if [ "$TASK_COUNT" -gt 0 ]; then
    echo "### Tasks (ordered by priority & dependencies)" >> "$OUTPUT"
    echo "" >> "$OUTPUT"

    echo "$TASKS" | jq -r '.tasks | sort_by(.priority == "low", .priority == "medium", .priority == "high" | not)[] | @base64' | while read -r TASK; do
      T_TITLE=$(echo "$TASK" | base64 -d | jq -r '.title')
      T_STATUS=$(echo "$TASK" | base64 -d | jq -r '.status')
      T_PRIORITY=$(echo "$TASK" | base64 -d | jq -r '.priority')
      T_DUE=$(echo "$TASK" | base64 -d | jq -r '.due_date // "no date"')
      T_DESC=$(echo "$TASK" | base64 -d | jq -r '.description // ""')
      T_ID=$(echo "$TASK" | base64 -d | jq -r '.id')

      if [ "$T_STATUS" = "completed" ]; then
        CHECKBOX="[x]"
      else
        CHECKBOX="[ ]"
      fi

      echo "- ${CHECKBOX} **${T_TITLE}** (Priority: ${T_PRIORITY}, Due: ${T_DUE})" >> "$OUTPUT"
      if [ -n "$T_DESC" ]; then
        echo "  > ${T_DESC}" >> "$OUTPUT"
      fi
      echo "  Task-ID: \`${T_ID}\`" >> "$OUTPUT"
      echo "" >> "$OUTPUT"
    done
  else
    echo "_No tasks linked to this milestone yet._" >> "$OUTPUT"
    echo "" >> "$OUTPUT"
  fi

  echo "---" >> "$OUTPUT"
  echo "" >> "$OUTPUT"
done

echo "Export complete: $OUTPUT"

Make it executable and run it:

chmod +x export-tasks-for-copilot.sh
./export-tasks-for-copilot.sh 2026-04-01 2026-09-30

Step 3: Use the Exported File with GitHub Copilot

The generated copilot-tasks.md file can be used in multiple ways:

Option A: Attach as Context in Copilot Chat (Recommended)

Open VS Code, start Copilot Chat in Agent Mode, and attach the file:

User:
#file:copilot-tasks.md

Work through the tasks in this file in order. Start with the first
uncompleted task under Milestone M1. For each task:
1. Implement the code changes described
2. Write tests (target 90%+ coverage)
3. Run `cargo test` to verify
4. Mark the task as done when complete
5. Move to the next task

Ask me before making architectural decisions not covered by the task.

Option B: Use as Custom Instructions (`.github/copilot-instructions.md`)

For long-running projects, place the task list in your repo:

mkdir -p .github
cp copilot-tasks.md .github/copilot-instructions.md

Copilot will automatically use this as context for every interaction.

Option C: Milestone-by-Milestone with Focused Prompts

For finer control, query tasks for a single milestone and prompt Copilot with just that scope:

# Export only tasks for the next milestone
curl -s http://localhost:3000/v1/calendar/events/{m3_event_id}/tasks \
  | jq -r '.tasks[] | "- [ ] \(.title)\n  > \(.description)\n"'

Then in Copilot Chat:

User:
Here are the tasks for Milestone M3 (Core Backend, due May 22):

- [ ] INV-001: Inventory CRUD API
  > REST endpoints: POST, GET, PATCH for /api/v1/inventory
  > Acceptance: input validation, audit log, 90% test coverage

- [ ] INV-003: Auth Middleware (OAuth 2.0 + RBAC)
  > JWT validation, role extraction, 3 roles: admin, buyer, warehouse_worker

Implement these in order. Start with INV-001.

Step 4: Mark Tasks Complete via API

After Copilot finishes a task, mark it as completed in PiSovereign so the dashboard and other agents stay in sync:

# Mark a single task as completed
curl -X POST http://localhost:3000/v1/tasks/{task_id}/complete

# Or update the status to in-progress first
curl -X PUT http://localhost:3000/v1/tasks/{task_id} \
  -H 'Content-Type: application/json' \
  -d '{"status": "in_progress"}'

This can be scripted into a post-commit hook or CI step for automatic tracking.

Recommended Workflow Summary

┌──────────────────────────────────────────────────────────────────┐
│                    PiSovereign (Planning)                       │
│  Agents create milestones + tasks in CalDAV                     │
└──────────────┬───────────────────────────────────────────────────┘
               │ GET /v1/calendar/events/.../tasks
               ▼
┌──────────────────────────────────────────────────────────────────┐
│              export-tasks-for-copilot.sh                        │
│  Generates copilot-tasks.md (ordered by milestone & priority)   │
└──────────────┬───────────────────────────────────────────────────┘
               │ Attach as context
               ▼
┌──────────────────────────────────────────────────────────────────┐
│              GitHub Copilot (Agent Mode)                        │
│  Executes tasks: implement → test → verify → next              │
└──────────────┬───────────────────────────────────────────────────┘
               │ POST /v1/tasks/{id}/complete
               ▼
┌──────────────────────────────────────────────────────────────────┐
│              PiSovereign (Tracking)                             │
│  Dashboard shows progress, agents see completed work            │
└──────────────────────────────────────────────────────────────────┘

Summary: With PiSovereign’s multi-agent system, a complete software project is systematically planned by 9 specialized agents. The result is concrete, prioritized tasks and milestones as calendar entries — ready for execution by GitHub Copilot or any other AI coding assistant.

PiSovereign Documentation