Activities - Define Architecture

#	Name	Abbrev.	Guidance	Actions
Inception 20
1	Analyze ESM Artifacts	DTA-1	Analyze ESM Artifacts Objective Extract capability requirements per architectural domain from the ESM output artifacts …	Read the 'DTA-1 Analyze ESM Artifacts' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Analyze ESM Artifacts ## Objective Extract capability requirements per architectural domain from the ESM output artifacts (user journey, screen flows, .feature files, IA guidelines). This structured requirements list feeds all subsequent DTA activities (DTA-02 through DTA-17). --- ## Process ### 1. Read User Journey - Extract domain entities (e.g., User, Playbook, Workflow, Activity, Skill) - Identify interaction patterns (CRUD, search, import/export, real-time updates) - Note personas and roles that imply auth/authorization requirements - Flag integration points (external systems, APIs, data sources) ### 2. Read Screen Flows - Identify UI complexity per screen type: - Simple: static content, read-only views - Moderate: forms, tables, filters, pagination - Complex: graphs, drag-and-drop, real-time, rich text editors - Count screen types to estimate frontend effort - Note navigation patterns (breadcrumbs, tabs, modals, wizards) ### 3. Read Feature Files (.feature) - Extract required capabilities from scenario steps: - CRUD operations per entity - Search and filter requirements - Authentication and authorization scenarios - Error handling and edge cases - Data validation rules - Map scenarios to capability domains (GUI_FORM, API_CRUD, AUTH_SESSION, etc.) ### 4. Read IA Guidelines - Extract design system requirements (component library, theming) - Note accessibility requirements (ARIA, keyboard navigation) - Identify responsive/multi-device needs ### 5. Compile Requirements per Domain Produce a structured list mapping ESM findings to the 16 architectural domains: ``` Domain: Application Blocks (DTA-02) - 5 bounded contexts identified: Auth, Methodology, Planning, MCP, Web UI - Dependency: Methodology → Planning (planning reads methodology) Domain: Integration & API Design (DTA-03) - MCP stdio interface required (read-only) - Web UI HTTP interface required (full CRUD) - No external 3rd party integrations identified Domain: Code Organization (DTA-04) - Monorepo structure implied (single Django project) - 3 layers visible: models, services, views Domain: Data Architecture (DTA-05) - 6 entities with relationships (graph-like) - Version tracking required - Import/export functionality needed ... (continue for all 16 domains) ``` --- ## Deliverables - ✅ Domain entities extracted from user journey - ✅ UI complexity assessed from screen flows - ✅ Capability domains mapped from .feature files - ✅ Structured requirements list produced for all 16 architectural domains - ✅ Ready to proceed with DTA-02 through DTA-17 ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - User Journey (Document, Required) — produced by Define User Journey (#36). - IA Guidelines (Document, Required) — produced by Define Information Architecture (#37).
2	Define Application Blocks	DTA-2	Define Application Blocks Objective Identify bounded contexts, domain packages, module boundaries, and dependency rules. Choose …	Read the 'DTA-2 Define Application Blocks' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Application Blocks ## Objective Identify bounded contexts, domain packages, module boundaries, and dependency rules. Choose the foundational architectural pattern (MVC, event-driven, modular monolith, microservices, etc.). --- ## Internal Process Every domain activity follows this structure: 1. Identify needs — what does ESM require for this domain? 2. Scan Skills — query Playbook Skills by `capability_domain` for this domain 3. Propose options — 2-3 approaches with Skill coverage, cost, risk 4. Record decision — user picks, rationale documented --- ## Decisions to Make ### 1. Bounded Contexts / Domain Packages - Review ESM entities and their relationships - Group entities into cohesive domain packages - Define which entities belong together (high cohesion) vs. which are separate concerns (loose coupling) - Example groupings: - `auth/` — User, Session, Permissions - `methodology/` — Playbook, Workflow, Activity, Skill - `planning/` — WorkPlan, Task, Estimation - `mcp/` — MCP protocol, tools, stdio interface ### 2. Module Boundaries & Dependency Rules - Define what can import what (dependency direction) - Identify shared kernel vs. independent modules - Example rules: - `planning` → depends on `methodology` (reads playbook structure) - `mcp` → depends on `methodology` (exposes methodology as tools) - `auth` → independent (no methodology dependency) - No circular dependencies allowed ### 3. Foundational Architectural Pattern Choose one: - MVC / MTV — Model-Template-View (Django default). Best for: server-rendered web apps with moderate complexity. - Event-Driven — Publish/subscribe, event sourcing. Best for: highly decoupled systems, real-time requirements. - Modular Monolith — Single deployable unit with strict module boundaries. Best for: starting simple with clear growth path. - Microservices — Independent deployable services. Best for: large teams, independent scaling needs. - Batch Processing — Scheduled jobs processing data in bulk. Best for: data pipelines, ETL. - Hybrid — Combine patterns (e.g., MVC for web + event-driven for async). ### 3a. UI Architecture Patterns (if system has a web/desktop UI) Define the presentation layer architecture: Rendering model: - Server-rendered — HTML generated on server (Django templates, Jinja2). Best for: testability, SEO, minimal JS. - SPA — Single Page Application (React, Vue, Svelte). Best for: rich interactivity, complex state. - Hybrid — Server-rendered with progressive enhancement (HTMX, Alpine.js, Turbo). Best for: server-side simplicity with dynamic UX. Layout pattern: - Single-panel — One main content area. Best for: simple CRUD, mobile-first. - Multi-panel — Split layout (navigation + content + detail). Best for: explorer-style UIs, dashboards. - Wizard/stepper — Sequential steps. Best for: complex forms, onboarding. Component interaction model: - Full page reload — Traditional links/forms. Simplest, most testable. - Partial updates — Server returns HTML fragments, client swaps them (HTMX, Turbo Frames). Testable with standard server-side tests. - Client-side state — JS manages state, talks to API (React+Redux, Vue+Pinia). Requires browser-based testing. Visualization approach (if applicable): - Server-generated — Graphviz, matplotlib, SVG generation on server. Best for: static/semi-static diagrams. - Client-rendered — D3.js, Cytoscape.js, Chart.js. Best for: interactive, real-time visualizations. - Hybrid — Server generates data, client renders. Best for: large datasets with interactive exploration. Document rationale for each choice, especially impact on testability and build complexity. ### 4. Scan Skills & Reference Implementations Query Playbook Skills where `capability_domain` in: - `APP_STRUCTURE` - `DOMAIN_MODELING` - `DEPENDENCY_INJECTION` Report coverage: ``` Skill Coverage for Application Blocks: APP_STRUCTURE \| [Django App Architecture Skill] ✅ \| Reference: Repository pattern, service layers, dependency rules \| Example: Mimir methodology/ app structure DOMAIN_MODELING \| [DDD Bounded Contexts Skill] ✅ \| Reference: Entity modeling, aggregate boundaries \| Example: Playbook → Workflow → Activity hierarchy DEPENDENCY_INJECTION \| ❌ No Skill - will create custom patterns \| Estimated impact: +1 iteration for pattern definition ``` If reference implementations exist: "Following Django app patterns from [Django App Architecture Skill](#skill-456), recommend service layer approach with estimated 2-day implementation." If gaps exist: "No Skill for Dependency Injection — will need to define patterns. Estimated impact: +1 iteration." --- ## Deliverables - ✅ Bounded contexts / domain packages identified and documented - ✅ Module dependency rules defined (what imports what) - ✅ Foundational pattern chosen with rationale - ✅ UI architecture patterns defined (if applicable): rendering model, layout, interaction model, visualization - ✅ Skill coverage assessed for this domain with reference implementations - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
3	Define Integration & API Design	DTA-3	Define Integration & API Design Objective Choose API style, versioning strategy, contract approach, external integration …	Read the 'DTA-3 Define Integration & API Design' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Integration & API Design ## Objective Choose API style, versioning strategy, contract approach, external integration patterns, and inter-service communication model. --- ## Decisions to Make ### 1. API Style Choose one or hybrid: - REST — Resource-oriented, HTTP verbs, JSON. Best for: standard CRUD web apps. - GraphQL — Query language, single endpoint. Best for: complex data fetching, mobile clients. - gRPC — Binary protocol, protobuf. Best for: internal service-to-service, high throughput. - MCP (Model Context Protocol) — stdio-based, tool-oriented. Best for: AI agent integration. - Hybrid — e.g., REST for web UI + MCP for AI agents. ### 2. API Versioning Strategy Choose one: - URL path — `/api/v1/playbooks/` → simple, visible, easy to route - Header — `Accept: application/vnd.mimir.v1+json` → clean URLs - Query param — `/api/playbooks/?version=1` → easy to test - No versioning — acceptable for internal-only APIs in early stages ### 3. Contract Approach Choose one: - Contract-first — Write OpenAPI/AsyncAPI spec first, generate code from it - Code-first — Write code first, generate spec from annotations/decorators - No formal contract — acceptable for internal APIs with single consumer ### 4. External Integrations - Identify 3rd party APIs the system consumes (if any) - Define webhook patterns (inbound/outbound) - Define event bus usage (if applicable) - Define retry and error handling for external calls ### 5. Inter-Service Communication If multiple services/processes exist: - Sync (HTTP/gRPC) — Request-response. Simple but creates coupling. - Async (Message Queue) — Fire-and-forget. Decoupled but complex. - Shared Database — Both processes read/write same DB. Simple but limits scaling. - File-based — Export/import via files. Simple for batch scenarios. ### 6. Implementation Patterns (document during/after implementation) For each chosen API style, document recurring implementation patterns as they emerge: - Service-to-transport mapping — How business logic maps to API endpoints/tools. Example: thin controller/tool wrapping a service method. - Sync/async boundary — If the API layer is async but business logic is sync (or vice versa), document the bridging pattern and any pitfalls discovered. - Protocol-specific constraints — Transport-layer constraints that affect architecture. Examples: stdio pollution in MCP, CORS in REST, N+1 in GraphQL. - Shared service layer — If multiple transports (e.g., web UI + API + MCP) share business logic, document how the service layer is structured to serve all consumers. - Error propagation — How errors from the service layer translate to API responses per transport (HTTP status codes, MCP error objects, gRPC status codes). > Note: This subsection starts as placeholder during DTA. Populate it during implementation and feed findings back into SAO.md via the "Discovered Patterns" section (DTA-18). ### 7. Scan Skills Query Playbook Skills where `capability_domain` in: - `API_REST` - `API_GRAPHQL` - `API_GRPC` - `API_CONTRACT` Report coverage and gaps. --- ## Deliverables - ✅ API style chosen with rationale - ✅ Versioning strategy defined - ✅ Contract approach selected - ✅ External integrations identified and patterns defined - ✅ Inter-service communication model chosen (if applicable) - ✅ Implementation patterns placeholder created (populated during/after implementation) - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
4	Define Code Organization	DTA-4	Define Code Organization Objective Define project layout, layer separation, naming conventions, and shared library approach. …	Read the 'DTA-4 Define Code Organization' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Code Organization ## Objective Define project layout, layer separation, naming conventions, and shared library approach. This translates the logical application blocks (DTA-02) into a physical directory and file structure. --- ## Decisions to Make ### 1. Repository Strategy Choose one: - Monorepo — Single repository, all code together. Best for: small teams, shared tooling. - Polyrepo — Separate repos per service/component. Best for: independent teams, different release cycles. - Monorepo with packages — Single repo with npm/pip workspaces. Best for: shared code with clear boundaries. ### 2. Directory Structure & Layer Separation Define the top-level project layout: - Where do models live? - Where do services (business logic) live? - Where do views/controllers live? - Where do templates/frontend assets live? - Where do tests live? - Where do docs live? Example (Django): ``` project/ ├── app_name/ │ ├── models/ # Data layer │ ├── services/ # Business logic │ ├── views/ # HTTP interface (Django views) │ └── templates/ # HTML templates ├── mcp/ # MCP interface ├── tests/ # All tests ├── docs/ # Documentation └── manage.py ``` ### 3. Naming Conventions Define rules for: - Files: snake_case.py, kebab-case.html, PascalCase.tsx - Classes: PascalCase - Functions/methods: snake_case - URLs: kebab-case (`/playbooks/playbook/list/`) - Database tables: snake_case (auto from models) - Constants: UPPER_SNAKE_CASE ### 4. Shared Libraries / Common Utilities - Where do cross-cutting concerns live? (logging, error handling, decorators) - How are shared types/interfaces defined? - Import rules: what can import from `common/`? ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `CODE_ORG` - `PROJECT_LAYOUT` Report coverage and gaps. --- ## Deliverables - ✅ Repository strategy chosen - ✅ Directory structure defined with layer separation - ✅ Naming conventions documented - ✅ Shared library approach defined - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
5	Define Data Architecture	DTA-5	Define Data Architecture Objective Choose database engine, define schema strategy, select data access patterns, and …	Read the 'DTA-5 Define Data Architecture' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Data Architecture ## Objective Choose database engine, define schema strategy, select data access patterns, and plan migration and caching approaches. --- ## Decisions to Make ### 1. Database Engine Choose one (or combination): - SQLite — File-based, zero config. Best for: desktop apps, prototypes, single-user. - PostgreSQL — Full-featured relational. Best for: production web apps, complex queries. - MySQL/MariaDB — Relational, widely supported. Best for: standard web apps. - Neo4j — Graph database. Best for: relationship-heavy data, graph traversals. - MongoDB — Document store. Best for: flexible schemas, rapid prototyping. - Combination — e.g., SQLite for FOB + Neo4j for HOMEBASE. Document rationale: performance needs, data model fit, team expertise, licensing. ### 2. Schema Strategy - Migration tool: Django migrations, Alembic, Flyway, manual SQL - Versioning: How are schema changes tracked? Numbered migrations? Timestamps? - Seed data: How is initial/test data loaded? Fixtures, factories, management commands? - Schema evolution: How are breaking changes handled? Expand-contract pattern? ### 3. Data Access Patterns Choose one: - ORM — Object-Relational Mapping (Django ORM, SQLAlchemy). Best for: standard CRUD. - Repository Pattern — Abstract interface over storage. Best for: storage-agnostic design, testability. - Raw Queries — Direct SQL/Cypher. Best for: complex queries, performance-critical paths. - Hybrid — ORM for simple CRUD + raw queries for complex operations. ### 4. Read/Write Separation & Caching - Is read/write separation needed? (CQRS pattern) - Cache strategy: application-level cache, query cache, HTTP cache - Cache invalidation approach - Connection pooling configuration ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `DB_RELATIONAL` - `DB_GRAPH` - `DATA_ACCESS` Report coverage and gaps. --- ## Deliverables - ✅ Database engine chosen with rationale - ✅ Schema strategy defined (migrations, versioning, seed data) - ✅ Data access pattern selected - ✅ Caching strategy defined (if applicable) - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
6	Define Test Strategy	DTA-6	Define Test Strategy Objective Define the test approach (prefer Test Trophy over Pyramid when integration-heavy), …	Read the 'DTA-6 Define Test Strategy' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Test Strategy ## Objective Define the test approach (prefer Test Trophy over Pyramid when integration-heavy), choose frameworks per layer, establish coverage targets, plan test data management, and configure CI integration for tests. Seed only: Record motivators, layer weights, and framework choices for inclusion in `docs/architecture/SAO.md` § Test Strategy via DTA-18. Do not finalize AT/E2E directory layout or step-library paths here — TFK-01 fleshes those details into the same SAO section before BPE. --- ## Decisions to Make ### 1. Trophy / Pyramid & Coverage Targets Define ratio and targets per level: - Unit tests — Isolated logic, services, utilities. Target: thin / focused coverage. - Integration tests — Views, DB queries, service interactions. Target: all CRUD paths (main bet when using Trophy). - Acceptance (AT) — BDD `.feature` scenarios; executable requirements. - E2E tests — Full user journeys via browser. Target: critical paths only. - Contract tests — API contract validation (if applicable). Define what "100% pass rate" means (all non-`@wip` tests must pass before declaring feature complete). ### 2. Frameworks per Layer Choose frameworks for each test level: - Unit: pytest, unittest, Jest, Vitest - Integration: pytest + Django test client, supertest - AT: behave-django (Django test client in steps) - E2E: Playwright, Cypress, Selenium - Contract: Pact, Schemathesis - Performance: Locust, k6, Artillery ### 3. Test Data Management - Fixtures: Static JSON/YAML fixtures loaded before tests - Factories: Dynamic data generation (factory_boy, Faker) - DB seeding: Management commands for consistent test state - Isolation: How are tests isolated? Transaction rollback? Fresh DB? - Makefile targets: `make test`, `make test-unit`, `make test-at`, `make test-e2e` ### 4. CI Integration - When do tests run? On every push? On PR? Nightly? - Failure gates: Which test failures block merge/deploy? - Test reporting: Where are results published? - Flaky test policy: How are flaky tests handled? ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `TEST_UNIT` - `TEST_INTEGRATION` - `TEST_E2E` Report coverage and gaps. ### 6. Agent test lanes (when SAO §17 applies) When the project has in-app LLM agents (SAO §17 is not "Not applicable"), seed four agent test lanes in the Test Strategy section for TFK-01 to flesh out before BPE: \| Lane \| Name \| CI gate \| Assert \| \|------\|------\|---------\|--------\| \| 1 \| Control-plane proofs \| PR when `AGENTS_ENABLED=true` \| PRF-* rows + CAP-004 ScriptedLLM + run trace (`assert_agent_story`) \| \| 2 \| Deterministic shell \| PR (normal integration) \| D0 pre-filter, JSON parse, validate-before-LLM — no LLM mock \| \| 3 \| Live contract eval \| Nightly / optional CD \| temp=0, schema/contract bounds only — not PR merge gate \| \| 4 \| Task performance quality \| Promotion band \| TASK-* golden oracle vs structured ground truth \| Seed only here: record that lanes 1–2 belong in default PR quality gates when agents are enabled; lanes 3–4 use separate `agent-eval.yml` (workflow_dispatch + schedule) and do not block merge. Do not finalize PRF test file paths, `tests/support/agent_story.py`, `tests/fixtures/llm_scripts/`, Makefile targets (`test-agent-proof`, `test-agent-quality`), or pytest markers here — TFK-01 fleshes lane wiring, directory layout, and CI/Makefile integration into SAO § Test Strategy before BPE. --- ## Deliverables - ✅ Test approach (Trophy/Pyramid) defined with coverage targets - ✅ Frameworks chosen per test level - ✅ Test data management approach defined - ✅ CI integration rules established - ✅ Skill coverage assessed for this domain - ✅ Seed decision recorded for SAO.md § Test Strategy (DTA-18); TFK-01 will flesh the section before BPE - ✅ Agent test lanes seeded (when SAO §17 applies); TFK-01 will flesh lane details before BPE
7	Define Performance & Scalability	DTA-7	Define Performance & Scalability Objective Define expected load profile, caching tiers, async processing strategy, connection …	Read the 'DTA-7 Define Performance & Scalability' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Performance & Scalability ## Objective Define expected load profile, caching tiers, async processing strategy, connection pooling, scaling approach, and capacity planning. --- ## Decisions to Make ### 1. Expected Load Profile Characterize the system's expected usage: - Concurrent users: How many at peak? - Requests/sec: Expected throughput per endpoint category - Data volume: How much data at launch? At 1 year? At 5 years? - Read/write ratio: What percentage of requests are reads vs writes? - Burst patterns: Are there predictable spikes (daily, weekly, seasonal)? ### 2. Caching Tiers Define caching at each level: - Application cache: In-memory cache (Django cache framework, Redis) - CDN: Static assets, pre-rendered pages - DB query cache: Query result caching, materialized views - Session cache: Session storage (DB, Redis, cookie-based) - HTTP cache: Cache-Control headers, ETags, conditional requests For each tier: what to cache, TTL, invalidation strategy. ### 3. Async Processing - Task queues: Celery, RQ, Dramatiq — for background jobs - Workers: How many? Auto-scaling? - Use cases: Email sending, PDF generation, data import/export, AI inference - Priority queues: Critical vs. best-effort tasks ### 4. Connection Pooling - DB connections: Pool size, timeout, max overflow - HTTP clients: Connection reuse for external API calls - WebSocket connections (if applicable) ### 5. Scaling Strategy - Horizontal: Add more instances behind load balancer - Vertical: Increase instance resources (CPU, RAM) - Auto-scaling: Triggers (CPU%, request count, queue depth) - Database scaling: Read replicas, sharding, connection pooling ### 6. Capacity Planning - Baseline resource requirements - Growth projections (linear, exponential) - Cost model per scaling tier - When to re-evaluate architecture ### 7. Scan Skills Query Playbook Skills where `capability_domain` in: - `PERF_CACHING` - `PERF_ASYNC` - `PERF_SCALING` Report coverage and gaps. --- ## Deliverables - ✅ Load profile characterized - ✅ Caching strategy defined per tier - ✅ Async processing approach chosen - ✅ Connection pooling configured - ✅ Scaling strategy defined - ✅ Capacity plan with cost model - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
8	Define Error Handling & Resilience	DTA-8	Define Error Handling & Resilience Objective Define error taxonomy, error response format, retry policies, circuit …	Read the 'DTA-8 Define Error Handling & Resilience' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Error Handling & Resilience ## Objective Define error taxonomy, error response format, retry policies, circuit breaker patterns, graceful degradation strategy, and idempotency requirements. --- ## Decisions to Make ### 1. Error Taxonomy Classify errors into categories: - Domain errors — Business rule violations (e.g., "Cannot delete released playbook") - Validation errors — Input validation failures (e.g., "Name is required") - Infrastructure errors — DB connection lost, disk full, OOM - External service errors — 3rd party API timeout, rate limit exceeded - Authentication/Authorization errors — Invalid session, insufficient permissions For each category: how is it logged, how is it presented to the user, what's the HTTP status code? ### 2. Error Response Format Define a standard error envelope: ```json { "error": { "code": "PLAYBOOK_NOT_FOUND", "message": "Playbook with ID abc-123 does not exist", "details": {}, "request_id": "req-xyz-789" } } ``` Decide: - Standard error codes (enum or free-text?) - User-facing messages (localization needed?) - Technical details (shown in dev, hidden in prod?) - Correlation/request IDs for tracing ### 3. Retry Policies For each type of retriable operation: - Which operations are retriable? (network calls, DB transactions, queue publish) - Backoff strategy: linear, exponential, jitter - Max attempts before giving up - Dead letter queue for permanently failed operations ### 4. Circuit Breakers For external service dependencies: - Failure threshold before circuit opens (e.g., 5 failures in 30 seconds) - Fallback behavior when circuit is open - Half-open recovery: how and when to retry - Monitoring: how to alert on open circuits ### 5. Graceful Degradation - Which features can operate in degraded mode? - How are users notified of degraded functionality? - Fallback data sources (cached data, default values) - Feature flags for emergency feature disabling ### 6. Idempotency - Which write operations must be idempotent? (payment processing, data import) - How is idempotency ensured? (idempotency keys, upsert patterns, deduplication) - Timeout handling: what happens if a request times out but the operation completed? ### 7. Scan Skills Query Playbook Skills where `capability_domain` in: - `ERR_HANDLING` - `ERR_RESILIENCE` - `ERR_RETRY` Report coverage and gaps. --- ## Deliverables - ✅ Error taxonomy defined with handling rules per category - ✅ Error response format standardized - ✅ Retry policies defined for retriable operations - ✅ Circuit breaker patterns defined (if applicable) - ✅ Graceful degradation strategy documented - ✅ Idempotency requirements identified - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
9	Define Infrastructure	DTA-9	Define Infrastructure Objective Define the local development environment, cloud provider and compute model, networking setup, …	Read the 'DTA-9 Define Infrastructure' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Infrastructure ## Objective Define the local development environment, cloud provider and compute model, networking setup, and Infrastructure as Code tooling. --- ## Decisions to Make ### 1. Local Development Environment - Containerization: Docker, Podman, or native? - Dev/prod parity: How close is local to production? - Makefile targets: `make provision` (install all deps), `make run` (start everything) - Required tools: Which CLI tools, SDKs, runtimes must be installed? - Environment variables: How are they managed locally? (.env file, direnv) ### 2. Cloud Provider & Compute Model Choose compute model: - Kubernetes (EKS/GKE/AKS) — Container orchestration. Best for: complex deployments, auto-scaling. - Container service (ECS/Cloud Run) — Managed containers. Best for: simpler container deployments. - Serverless (Lambda/Cloud Functions) — Event-driven functions. Best for: sporadic workloads. - VMs (EC2/Compute Engine) — Traditional. Best for: legacy apps, specific OS needs. - PaaS (Heroku/Railway/Render) — Managed platform. Best for: fast start, less ops overhead. - Desktop only — No cloud. Best for: single-user desktop applications. ### 3. Networking - VPC: Network isolation, subnets (public/private) - DNS: Domain management, Route53/Cloudflare - Load balancing: ALB/NLB, health checks, SSL termination - CDN: Static asset distribution, edge caching ### 4. Infrastructure as Code Choose one: - AWS CDK — TypeScript/Python, AWS-native. Best for: AWS-only, programmatic infra. - Terraform — HCL, multi-cloud. Best for: cloud-agnostic, declarative. - Pulumi — General-purpose languages. Best for: developers who prefer Python/TS. - CloudFormation — YAML/JSON, AWS-native. Best for: simple AWS setups. - None — Manual/console setup. Best for: prototypes, desktop apps. ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `INFRA_LOCAL` - `INFRA_CLOUD` - `INFRA_K8S` Report coverage and gaps. --- ## Deliverables - ✅ Local dev environment defined with provisioning instructions - ✅ Cloud provider & compute model chosen with rationale - ✅ Networking architecture defined - ✅ IaC tool selected - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
10	Define CI/CD Pipeline	DTA-10	Define CI/CD Pipeline Objective Choose CI platform, define pipeline stages, configure artifact registry, set promotion …	Read the 'DTA-10 Define CI/CD Pipeline' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define CI/CD Pipeline ## Objective Choose CI platform, define pipeline stages, configure artifact registry, set promotion gates, and establish trunk-based development flow. --- ## Decisions to Make ### 1. CI Platform Choose one: - GitHub Actions — GitHub-native, YAML workflows. Best for: GitHub-hosted repos. - GitLab CI — GitLab-native, `.gitlab-ci.yml`. Best for: GitLab-hosted repos. - Jenkins — Self-hosted, Groovy pipelines. Best for: complex custom pipelines. - CircleCI — Cloud-hosted, YAML config. Best for: fast builds, Docker-native. - None — Local-only builds. Best for: desktop apps, early prototypes. ### 2. Pipeline Stages Define the standard pipeline stages: ``` lint → test → build → publish → deploy ``` For each stage: - What runs? (commands, scripts) - What triggers it? (push, PR, tag, manual) - What blocks the next stage? (failure criteria) - Estimated duration target ### 3. Artifact Registry - Container images: Docker Hub, ECR, GCR, GitHub Container Registry - Packages: npm registry, PyPI, private registry - Build artifacts: S3, GCS, artifact storage in CI platform - Retention policy: How long are artifacts kept? ### 4. Promotion Gates - Automated gates: All tests pass, linting clean, security scan clean - Manual gates: Human approval for production deploy - Environment promotion: dev → staging → production - Rollback trigger: Automated on health check failure? Manual only? ### 5. Trunk-Based Development Flow - Branch strategy: Trunk-based (short-lived feature branches, merge to main) - PR requirements: Reviews, CI pass, no conflicts - Merge strategy: Squash, rebase, merge commit - Release tagging: Semantic versioning, automated changelog ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `CICD_BUILD` - `CICD_DEPLOY` - `CICD_PIPELINE` Report coverage and gaps. --- ## Deliverables - ✅ CI platform chosen - ✅ Pipeline stages defined with triggers and gates - ✅ Artifact registry configured - ✅ Promotion gates established - ✅ Trunk-based flow documented - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
11	Define Release & Rollback	DTA-11	Define Release & Rollback Objective Choose deployment strategy, define version tagging, establish rollback triggers and …	Read the 'DTA-11 Define Release & Rollback' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Release & Rollback ## Objective Choose deployment strategy, define version tagging, establish rollback triggers and procedures, and set release cadence. --- ## Decisions to Make ### 1. Deployment Strategy Choose one: - Blue-Green — Two identical environments, switch traffic. Best for: zero-downtime, instant rollback. - Canary — Gradual traffic shift to new version. Best for: risk mitigation, large user base. - Rolling Update — Replace instances one by one. Best for: K8s default, resource-efficient. - Recreate — Stop old, start new. Best for: stateful apps, dev environments. - Feature Flags — Deploy code dark, enable via flags. Best for: decoupling deploy from release. ### 2. Version Tagging & Changelog - Semantic Versioning: MAJOR.MINOR.PATCH - Tagging: Git tags on release commits - Changelog generation: Automated from commit messages (conventional commits) - Release notes: Automated or manual? Where published? ### 3. Rollback Triggers - Automated: Health check failures, error rate spike, latency threshold - Manual: Operator decision, customer report - Rollback procedure: Revert traffic? Redeploy previous version? DB rollback? - Rollback time target: How fast must rollback complete? ### 4. Release Cadence & Policies - Cadence: Continuous delivery (every merge)? Weekly? Sprint-aligned? - Freeze policies: Code freeze before major releases? - Hotfix process: How are urgent fixes deployed outside normal cadence? - Communication: Who is notified of releases? How? ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `RELEASE_DEPLOY` - `RELEASE_ROLLBACK` Report coverage and gaps. --- ## Deliverables - ✅ Deployment strategy chosen with rationale - ✅ Version tagging and changelog approach defined - ✅ Rollback triggers and procedures established - ✅ Release cadence and policies documented - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
12	Define Observability	DTA-12	Define Observability Objective Define logging, metrics, distributed tracing, dashboards, alerting, and incident response approach. Decisions …	Read the 'DTA-12 Define Observability' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Observability ## Objective Define logging, metrics, distributed tracing, dashboards, alerting, and incident response approach. --- ## Decisions to Make ### 1. Logging - Format: Structured logging (JSON) vs. plain text - Library: Python logging, structlog, loguru - Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL — when to use each - Aggregation: CloudWatch, ELK stack, Loki, local file rotation - Retention: How long are logs kept? Per environment? - Sensitive data: What must NOT be logged? (passwords, tokens, PII) ### 2. Metrics - Application metrics: Request count, response time, error rate, queue depth - Infrastructure metrics: CPU, memory, disk, network - Business metrics: Features used, user actions, conversion rates - Tools: Prometheus, CloudWatch Metrics, Datadog, StatsD - Naming convention: `app.request.duration`, `app.db.query.count` ### 3. Distributed Tracing - Correlation IDs: How are requests traced across services/processes? - Span collection: OpenTelemetry, Jaeger, Zipkin, X-Ray - Trace sampling: Sample all requests or a percentage? - Trace context propagation: How are trace IDs passed between services? ### 4. Dashboards & Alerting - Dashboard tool: Grafana, CloudWatch Dashboards, Datadog - SLIs/SLOs: Service Level Indicators and Objectives - e.g., "99.9% of requests complete in < 500ms" - e.g., "Error rate < 0.1%" - Alert channels: Email, Slack, PagerDuty, OpsGenie - Alert severity levels: P1 (page immediately) through P4 (review next day) ### 5. Incident Response - Runbooks: Standard operating procedures for common incidents - Postmortems: Blameless postmortem template and cadence - On-call rotation: Who is on call? How are they reached? - Escalation path: P1 → on-call → team lead → management ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `OBS_LOGGING` - `OBS_METRICS` - `OBS_TRACING` Report coverage and gaps. --- ## Deliverables - ✅ Logging strategy defined (format, aggregation, retention) - ✅ Metrics approach chosen (tools, naming, key metrics) - ✅ Distributed tracing configured (if applicable) - ✅ Dashboards & alerting defined (SLIs/SLOs, alert channels) - ✅ Incident response procedures established - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
13	Define Config & Secrets	DTA-13	Define Config & Secrets Objective Define environment configuration strategy, secrets management, feature flag approach, and …	Read the 'DTA-13 Define Config & Secrets' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Config & Secrets ## Objective Define environment configuration strategy, secrets management, feature flag approach, and per-environment overrides. --- ## Decisions to Make ### 1. Environment Configuration - Config source: Environment variables, config files (.env, YAML, TOML), Django settings - Per-environment overrides: How do dev/staging/prod configs differ? - Config validation: Are required configs validated at startup? - Config documentation: Where are all config options documented? Example patterns: ``` # .env file (local) DEBUG=True DATABASE_URL=sqlite:///db.sqlite3 SECRET_KEY=dev-only-key # Production (env vars from secrets manager) DEBUG=False DATABASE_URL=postgresql://... SECRET_KEY=<from-vault> ``` ### 2. Secrets Management Choose approach: - Environment variables — Simple, works everywhere. Risk: leakage in logs/errors. - Secrets manager — AWS Secrets Manager, HashiCorp Vault, Azure Key Vault. Best for: production. - Sealed secrets — Encrypted in Git, decrypted in cluster. Best for: GitOps. - .env files — Local only, gitignored. Best for: development. - Django's SECRET_KEY rotation — How often? How to rotate without downtime? ### 3. Feature Flags - Approach: Config-based, database-based, external service (LaunchDarkly, Unleash) - Flag types: Boolean (on/off), percentage rollout, user segment - Management: Who can toggle flags? Via UI, CLI, API? - Cleanup: How are stale flags removed? ### 4. Scan Skills Query Playbook Skills where `capability_domain` in: - `CONFIG_ENV` - `CONFIG_SECRETS` - `CONFIG_FLAGS` Report coverage and gaps. --- ## Deliverables - ✅ Environment configuration strategy defined - ✅ Secrets management approach chosen - ✅ Feature flag approach defined (if applicable) - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
14	Define Security	DTA-14	Define Security Objective Define authentication model, authorization approach, API security measures, dependency scanning, and OWASP …	Read the 'DTA-14 Define Security' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Security ## Objective Define authentication model, authorization approach, API security measures, dependency scanning, and OWASP compliance targets. --- ## Decisions to Make ### 1. Authentication Model Choose one: - Session-based — Server-side sessions, cookie-based. Best for: traditional web apps. - JWT — Stateless tokens. Best for: SPAs, mobile apps, microservices. - OAuth2/OIDC — Delegated auth via provider. Best for: SSO, social login. - API keys — Simple key-based auth. Best for: machine-to-machine. - mTLS — Mutual TLS. Best for: service-to-service in zero-trust. Decide: - Password hashing algorithm (bcrypt, Argon2, PBKDF2) - Session/token lifetime and refresh strategy - MFA requirements (if any) - Password complexity rules ### 2. Authorization Model Choose one: - RBAC — Role-Based Access Control. Roles → Permissions. Best for: most web apps. - ABAC — Attribute-Based Access Control. Policy rules on attributes. Best for: complex permission logic. - Object-level — Per-object ownership checks. Best for: multi-tenant apps. - Hybrid — RBAC for coarse-grained + object-level for fine-grained. Define permission model: - What roles exist? - What can each role do? - How are permissions checked in code? (decorators, middleware, service layer) ### 3. API Security - Rate limiting: Per-user, per-endpoint, per-IP - CORS: Allowed origins, methods, headers - Input validation: Where validated? (serializer, model, view) - CSRF protection: Tokens, SameSite cookies - Content Security Policy: CSP headers configuration ### 4. Dependency Scanning - Tool: Dependabot, Snyk, pip-audit, npm audit, Trivy - Cadence: On every PR? Nightly? Weekly? - Policy: Block merge on critical CVEs? Warning only? - License compliance: Check for incompatible licenses? ### 5. OWASP Compliance Target OWASP Top 10 coverage: - A01: Broken Access Control - A02: Cryptographic Failures - A03: Injection - A05: Security Misconfiguration - A07: Identification and Authentication Failures For each: current mitigation strategy. ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `SEC_AUTH` - `SEC_AUTHZ` - `SEC_API` - `SEC_SCAN` Report coverage and gaps. --- ## Deliverables - ✅ Authentication model chosen with configuration details - ✅ Authorization model defined with role/permission structure - ✅ API security measures configured - ✅ Dependency scanning tool and policy established - ✅ OWASP compliance targets set - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
15	Define Backup & Recovery	DTA-15	Define Backup & Recovery Objective Define backup schedule, retention policy, RTO/RPO targets, disaster recovery plan, …	Read the 'DTA-15 Define Backup & Recovery' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Backup & Recovery ## Objective Define backup schedule, retention policy, RTO/RPO targets, disaster recovery plan, and data export/import procedures. --- ## Decisions to Make ### 1. Backup Schedule & Retention - Backup frequency: Hourly, daily, weekly, continuous (WAL archiving) - Backup type: Full, incremental, differential - Retention policy: How long are backups kept? - Daily backups: keep 7 days - Weekly backups: keep 4 weeks - Monthly backups: keep 12 months - Storage: Where are backups stored? (S3, GCS, local disk, off-site) - Encryption: Are backups encrypted at rest? ### 2. RTO & RPO Targets - RPO (Recovery Point Objective): Maximum acceptable data loss - e.g., "15 minutes" means we can lose at most 15 minutes of data - RTO (Recovery Time Objective): Maximum acceptable downtime - e.g., "1 hour" means the system must be restored within 1 hour - These targets drive backup frequency and recovery procedure complexity ### 3. Disaster Recovery Plan - Failover: Automatic or manual? - Geo-redundancy: Multi-region, multi-AZ, single region? - Recovery procedure: Step-by-step restoration from backup - DR testing: How often is the recovery procedure tested? - Communication plan: Who is notified during a disaster? ### 4. Data Export/Import - Export formats: JSON, CSV, SQL dump, custom format - Export triggers: Manual, scheduled, API-driven - Import validation: How is imported data validated? - Makefile targets: `make backup`, `make restore`, `make export-data` ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `BACKUP_DB` - `BACKUP_DR` Report coverage and gaps. --- ## Deliverables - ✅ Backup schedule and retention policy defined - ✅ RTO/RPO targets set with rationale - ✅ Disaster recovery plan documented - ✅ Data export/import procedures defined - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
16	Define Developer Experience	DTA-16	Define Developer Experience Objective Define IDE setup, code quality tooling, local debugging approach, onboarding flow, …	Read the 'DTA-16 Define Developer Experience' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Developer Experience ## Objective Define IDE setup, code quality tooling, local debugging approach, onboarding flow, and inner loop speed targets. --- ## Decisions to Make ### 1. IDE Setup - Recommended IDE: VS Code, PyCharm, Cursor, Windsurf, etc. - Extensions/plugins: Which are required? Which are recommended? - Workspace settings: Shared `.vscode/settings.json` or `.idea/` config - Debug configurations: Launch configs for backend, frontend, tests - AI assistant config: MCP server configuration for Mimir integration ### 2. Code Quality Tooling - Linter: flake8, ruff, pylint, eslint - Formatter: black, ruff format, prettier - Type checker: mypy, pyright - Pre-commit hooks: Which checks run before commit? - Configuration files: `pyproject.toml`, `.flake8`, `.prettierrc` - Makefile targets: `make lint`, `make format`, `make typecheck` ### 3. Local Debugging - Breakpoint debugging: IDE debugger, pdb, ipdb - Log tailing: How to watch logs in real-time during development - DB inspection: Django admin, DB browser, management commands - Network inspection: How to inspect HTTP requests (Django Debug Toolbar) - Test debugging: How to run and debug individual tests ### 4. Onboarding - README: What must be in the root README for a new developer? - `make provision`: Single command to install all prerequisites - `make run`: Single command to start the full application - Time-to-first-feature target: "New developer ships first feature within X hours" - Onboarding checklist: Step-by-step from `git clone` to running tests ### 5. Inner Loop Speed - Hot reload: Auto-restart on file changes (Django runserver, webpack HMR) - Incremental builds: Only rebuild what changed - Test watch mode: Auto-run affected tests on save - Build performance: Target build times per operation ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `DEVEX_IDE` - `DEVEX_QUALITY` - `DEVEX_ONBOARD` Report coverage and gaps. --- ## Deliverables - ✅ IDE setup documented with recommended extensions and debug configs - ✅ Code quality tooling configured (linter, formatter, pre-commit) - ✅ Local debugging approach defined - ✅ Onboarding flow documented with time-to-first-feature target - ✅ Inner loop speed targets set - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
17	Define Documentation Strategy	DTA-17	Define Documentation Strategy Objective Define Architecture Decision Record (ADR) process, API documentation approach, living documentation …	Read the 'DTA-17 Define Documentation Strategy' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Documentation Strategy ## Objective Define Architecture Decision Record (ADR) process, API documentation approach, living documentation standards, runbook format, and knowledge base structure. --- ## Decisions to Make ### 1. Architecture Decision Records (ADRs) - Template: Standard ADR format (Title, Status, Context, Decision, Consequences) - Storage location: `docs/architecture/decisions/` or `docs/adr/` - Numbering: Sequential (ADR-001, ADR-002, ...) - Review process: PR-based? Team discussion? Informal? - When to write: Any significant architecture or technology choice ### 2. API Documentation - Approach: OpenAPI/Swagger spec generation - Generation: Contract-first (write spec, generate code) or code-first (generate spec from code) - Publishing: Auto-published on build? Swagger UI endpoint? - MCP tool documentation: How are MCP tools documented? - Versioning: Spec versioned with API version ### 3. Living Documentation - Code comments policy: When to comment (non-obvious logic), when NOT to comment (obvious code) - Docstring standards: Sphinx format with `:param:`, `:return:`, `:raises:` and examples - Type hints: Required on all public methods and functions - README hierarchy: Root README → app-level READMEs → module docs ### 4. Runbook Standards - Format: Markdown with structured sections (Trigger, Impact, Steps, Verification) - Storage: `docs/runbooks/` or alongside infrastructure code - Update cadence: After every incident that reveals a gap - Review: Quarterly runbook review for staleness ### 5. Knowledge Base - Wiki: GitHub Wiki, Confluence, Notion, or docs/ in repo - Onboarding guides: For new developers, new operators - FAQ: Common questions and troubleshooting - Search: How is documentation discoverable? ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `DOCS_ADR` - `DOCS_API` - `DOCS_RUNBOOK` Report coverage and gaps. --- ## Deliverables - ✅ ADR process established with template and storage location - ✅ API documentation approach chosen - ✅ Living documentation standards defined (comments, docstrings, type hints) - ✅ Runbook standards set - ✅ Knowledge base structure defined - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
18	Define MCP Architecture	DTA-18	Define MCP Architecture Condition: Run only if the system exposes tools or resources via the …	Read the 'DTA-18 Define MCP Architecture' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define MCP Architecture Condition: Run only if the system exposes tools or resources via the Model Context Protocol. Skip and write "Not applicable" in SAO §18 if MCP is not in scope. Depends on DTA-03 (API style chosen). Reference: Playbook artifact MCP FastMCP Reference Architecture (latest released Edda version). ## Objective Decide the MCP integration case (A / B / hybrid), transport topology, tool inventory, and authentication pattern; document all decisions in SAO §18. ## Process 1. Fetch the latest MCP FastMCP Reference Architecture from the playbook and read the Purpose & Mission Assessment sections before answering any question below. 2. Answer mission questions — determine integration case and transport. 3. Inventory tools — decide which service callables become MCP tools. 4. Design auth pattern — process user, PAT per call, or both. 5. Handle stdout hygiene if stdio transport is selected. 6. Record decisions for SAO §18. ## Decisions to Make ### 1. Mission Assessment (Q1–Q7) \| # \| Question \| Answer \| Impact \| \|---\|----------\|--------\|--------\| \| Q1 \| Who are the MCP clients? (AI IDE, Claude Desktop, custom script, cloud AI) \| \| Transport and auth \| \| Q2 \| Embed business logic or delegate to HTTP API? \| \| Case A vs B vs hybrid \| \| Q3 \| How is user identity established per tool call? \| \| Auth pattern \| \| Q4 \| Are any tools destructive? (write, delete, deploy) \| \| HITL and write-tool policy \| \| Q5 \| Low-latency local IDE integration required? \| \| stdio transport \| \| Q6 \| Multi-tenant or remote-client access required? \| \| HTTP+SSE transport \| \| Q7 \| Stdout logging interference needs prevention? \| \| Log routing for stdio \| ### 2. Integration Case - [ ] Case A — Service Bridge: MCP calls internal service layer directly. Best for single-deployment systems. - [ ] Case B — API Facade: MCP calls the public HTTP API. Best for multi-tenant / remote clients. - [ ] Hybrid: Mix of A and B. Rationale: _____ ### 3. Transport Topology \| Target \| Transport \| Port / Path \| Notes \| \|--------\|-----------\|-------------\|-------\| \| Local IDE (Cursor, Claude Desktop) \| stdio \| n/a \| Requires stdout hygiene \| \| Remote AI clients \| HTTP+SSE \| :8001/mcp \| Auth header required \| Topology decision: stdio only / HTTP+SSE only / Both (dual server) ### 4. Tool Inventory \| Tool name \| Service method \| Write? \| HITL? \| Case \| \|-----------\|----------------\|--------\|-------\|------\| \| \| \| \| \| \| Write-tool policy: Require explicit confirmation param / HITL prompt before execute / Audit log only ### 5. Authentication Pattern Selected pattern(s): Process user / PAT per call / Session cookie / Mixed PAT injection point: Tool argument (explicit) / HTTP header (Bearer — avoids prompt injection) ### 6. Stdout Hygiene (if stdio) - Redirect all logging to stderr or file - Suppress third-party libraries that print to stdout - Add T3 test verifying no stdout noise on server boot ### 7. Case B: API Readiness Contract (if Case B or hybrid) \| Tool \| HTTP endpoint \| Method \| Auth header \| \|------\|---------------\|--------\|-------------\| \| \| \| \| \| ### 8. Scan Skills Query Skills where `capability_domain` in: MCP, API_INTEGRATION, AUTH. Report gaps. ## Deliverables - Mission questions answered (Q1–Q7) - Integration case chosen (A / B / hybrid) with rationale - Transport topology defined - Tool inventory table (tool → service method → write? → HITL?) - Auth pattern defined with injection point - Stdout hygiene addressed (if stdio) - API readiness contract defined (if Case B) - Skill coverage assessed - Decision recorded for SAO §18 (DTA-18)
19	Define AI Agent Architecture	DTA-19	Define AI Agent Architecture Condition: Run only if the system has in-app LLM agents (agentic …	Read the 'DTA-19 Define AI Agent Architecture' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define AI Agent Architecture Condition: Run only if the system has in-app LLM agents (agentic loops, plan/worker execution, or LLM calls inside the application). Skip and write "Not applicable" in SAO §17 if none of: in-app agentic loop, LLM calls initiated by the app, plan/worker execution. Reference: Playbook artifact AI Agent Reference Architecture (latest released Edda version). ## Objective Confirm components (Part 1), pick design patterns and scenarios (Part 2), choose serving mode (Part 3), select capabilities (`CAP-xxx`), choose an assembly template, and record decisions in SAO §17. ## Process 1. Fetch the latest AI Agent Reference Architecture from the playbook. 2. Read How to use this document and Part 1 — Components; complete infra, model, vector (if needed), framework, memory, and observability checklist in SAO §17. 3. Pick Part 2 — Design patterns and primary SC-xx scenario(s); use Part 5 — Quick reference for secondary CAP additions. 4. Choose Part 3 — Serving mode (real-time, batch/queue, or both). 5. Copy required + chosen optional CAP-IDs into SAO §17 from Part 4.1 Capability table. 6. Confirm dependencies in Part 4.3 Module wiring. 7. Note starting assembly template from Part 4.4 (T-01, T-02, T-03, or T-00 custom). 8. Name integration proof test IDs (`PRF-SCxx-xx`, `PRF-OBS-01`) from Part 4.5 as DoD gate. 9. If both SC-02 and SC-05 are selected, read Pattern 5 · SC-02 × SC-05 · Full rescan invariants and record checklist in SAO §17. 10. If Pattern 4 / SC-01 with large domain state, decide dual execution path (CAP-037, CAP-038, CAP-039) and memory tiers (Component 5 / CAP-091–094). 11. Record Pattern 4 anti-pattern checklist (mechanical step execution; worker failure bridge) when CAP-060 selected. 12. Record decisions for SAO §17 via Write SAO.md (Activity 59). ## Decisions to Make ### 1. Infra layer (Component 1) \| Decision \| Choice \| Rationale \| \|----------\|--------\|-----------\| \| LLM provider \| anthropic / openai / ollama / … \| \| \| Ollama readiness probe at startup \| Yes / No / N/A \| \| \| Broker + result backend (CAP-060) \| Configured / N/A \| \| \| Secrets server-side only \| Yes \| \| ### 2. Vector tier (Component 3) \| Decision \| Choice \| Rationale \| \|----------\|--------\|-----------\| \| Vector store needed \| Yes / No \| \| \| Backend \| pgvector / dedicated / in-process \| \| \| CAP-090 / CAP-094 selected \| Yes / No \| \| ### 3. Design pattern & scenario selection Read Part 2 pattern sections before ticking. Record primary scenario(s) and rationale. \| SC-ID \| Pattern \| Name \| Selected? \| Rationale \| \|-------\|---------\|------\|-----------\|-----------\| \| SC-01 \| 4 \| Conversational planner \| \| \| \| SC-02 \| 2 \| Field extractor / batch ingest \| \| \| \| SC-03 \| 7 \| Compiled pipeline \| \| \| \| SC-04 \| 3 \| Event-driven nudge \| \| \| \| SC-05 \| 5 \| Governed mutations \| \| \| ### 4. Serving mode (Part 3) \| Mode \| Selected? \| CAP-IDs \| \|------\|-----------\|---------\| \| Real-time (3.1) \| \| CAP-040, CAP-003, CAP-100 \| \| Batch / queue (3.2) \| \| CAP-060–066 \| \| Observability for serving (3.3) \| \| CAP-101, CAP-100 \| ### 5. Dual execution path (Pattern 4 / SC-01 with large state) \| Decision \| Choice \| Rationale \| \|----------\|--------\|-----------\| \| Context snapshot in chat (CAP-037) \| Yes / No \| \| \| Snapshot invalidation on writes (CAP-038) \| Yes / No \| \| \| Mutation-only tools in conversation (CAP-039) \| Yes / No \| \| \| Full tool registry in plan worker only \| Yes / No \| \| ### 6. Memory tiers (Component 5) \| Tier \| CAP-IDs \| Selected? \| Rationale \| \|------\|---------\|-----------\|-----------\| \| 1 Hot snapshot \| 037, 038, 039 \| \| \| \| 2 Semantic search \| 091 \| \| \| \| 3 AI profile \| 092 \| \| \| \| 4 Reference library \| 094, 090 \| \| \| \| 5 Entity notes \| 093 \| \| \| ### 7. Capability checklist From Part 4.1 — tick every CAP your project implements: \| CAP-ID \| Name \| Required for SC? \| Implement? \| Module path in project \| \|--------\|------\|------------------\|------------\|------------------------\| \| CAP-001 \| LLM Port protocol \| \| \| \| \| CAP-037 \| Context snapshot hydration \| \| \| \| \| CAP-038 \| Snapshot invalidation hooks \| \| \| \| \| CAP-039 \| Dual tool exposure \| \| \| \| \| CAP-091 \| Semantic context search \| \| \| \| \| CAP-092 \| AI-managed profile memory \| \| \| \| \| CAP-093 \| Entity notes graph \| \| \| \| \| CAP-094 \| Reference knowledge library \| \| \| \| \| CAP-101 \| Agent interaction trace \| \| \| \| \| … \| (copy remaining rows for each selected CAP) \| \| \| \| Minimum: all required CAP-IDs from your selected SC-xx row in Part 5 — Scenario index. ### 8. Assembly template - [ ] T-01 Planner (SC-01 / Pattern 4) - [ ] T-02 Field (SC-02 / Pattern 2) - [ ] T-03 Pipeline (SC-03) - [ ] T-00 Custom — list CAP-IDs: _______________ ### 9. Agent identities (CAP-121, CAP-122) \| Identity \| Role \| Model tier \| Allowed tools \| \|----------\|------\|------------\|---------------\| \| \| \| planning / execution / field \| \| ### 10. Agent Blackboard (if CAP-070 selected) - Durability tier: A — in-process / B — run-persistent - Schema keys: phase, hypothesis, current_plan, last_actions, next_intent - Max board size (chars): ______ ### 11. Worker anti-patterns (if CAP-060 selected) - [ ] Worker uses LLM per step (CAP-054) — not mechanical tool script (Pattern 4 anti-patterns) - [ ] Worker failure bridged to UI (CAP-100 plan_failed and/or chat context injection) - [ ] PRF-SC01-06 mapped if hybrid worker is new ### 12. Observability (Component 6 / CAP-101) - correlation_id header/name: ______ - Cost rate table location: ______ - PRF-OBS-01 test file: ______ ### 13. Integration proof (DoD gate) \| PRF ID \| Scenario \| Test file \| Selected? \| \|--------\|----------\|-----------\|-----------\| \| PRF-SC02-01 \| SC-02 thinking JSON \| \| \| \| PRF-SC02-02 \| SC-02 parse fail loud \| \| \| \| PRF-SC02-03 \| SC-02 domain D0 pre-filter \| \| \| \| PRF-SC02-04 \| SC-02 D1 parse fail loud \| \| \| \| PRF-SC01-01 \| SC-01 plan handoff \| \| \| \| PRF-SC01-02 \| SC-01 429 retry \| \| \| \| PRF-SC01-03 \| SC-01 blackboard retain \| \| \| \| PRF-SC01-04 \| SC-01 dual tool exposure \| \| \| \| PRF-SC01-05 \| SC-01 snapshot invalidation \| \| \| \| PRF-SC01-06 \| SC-01 no mechanical worker \| \| \| \| PRF-SC01-07 \| SC-01 worker failure bridge \| \| \| \| PRF-SC05-01 \| SC-05 HITL \| \| \| \| PRF-SC05-02 \| SC-02+05 full rescan invariants \| \| \| \| PRF-OBS-01 \| all \| correlation + usage trace \| \| \| ### 14. SC-02 × SC-05 full rescan (if both selected) From Pattern 5 · SC-02 × SC-05 · Full rescan invariants: - [ ] Rescan delete ops meet auto-apply confidence threshold (or rescan disables partial auto-apply) - [ ] ChangeSet apply ordering: deletes → updates → adds when rescan flag is set - [ ] PRF-SC05-02 mapped to integration test file ### 15. Scan Skills Query Skills where `capability_domain` in: AI_AGENT, LLM_INTEGRATION, ASYNC_TASK, OBSERVABILITY. Report gaps. ### 16. Task performance quality (TASK-) From artifact 56 Part 4.6 — Task performance quality. Mirror the Part 4.5 Integration proof* table style. These are lane 4 evals — measure model + prompt + tools against structured ground truth, not orchestration wiring (lane 1) or deterministic parse/validate (lane 2). \| TASK ID \| Scenario \| Oracle type \| Pass band \| Selected? \| Test file \| \|---------\|----------\|-------------\|-----------\|-----------\|-----------\| \| TASK-SC02-01 \| SC-02 \| set_recall \| recall ≥ 0.95, extras ≤ 1 \| \| \| \| TASK-SC02-02 \| SC-02 \| graph_diff \| zero unexpected deletes on rescan corpus \| \| \| \| TASK-SC01-01 \| SC-01 \| plan_steps \| expected tool sequence + final state \| \| \| \| TASK-SC05-01 \| SC-05 \| hitl_rate \| destructive ops blocked until approval \| \| \| \| … \| (copy remaining Part 4.6 rows for selected SC-xx) \| \| \| \| \| Eval vs merge DoD: \| Gate \| Lanes \| When \| Blocks merge? \| \|------\|-------\|------\|---------------\| \| Merge DoD \| 1–2 \| PR when `AGENTS_ENABLED=true` \| Yes — PRF-* under CAP-004 ScriptedLLM; lane 2 deterministic shell in normal integration \| \| Contract eval \| 3 \| Nightly / optional CD cert \| No — temp=0 schema/contract bounds only \| \| Promotion DoD \| 4 \| `make test-agent-quality` / scheduled eval \| No — regression vs last certified TASK-* band; human promotion decision \| Record chosen TASK rows, fixture paths (`tests/fixtures/agent_tasks/<task-id>/`), and certified pass bands in SAO §17. Full catalog fields (`fixture_ref`, `n_runs`, oracle asserts) live in artifact 56 Part 4.6 — link there; do not duplicate prose in SAO. ## Deliverables - Infra + vector tier decisions documented - Primary pattern(s) and SC-xx scenario(s) chosen with rationale - Serving mode (Part 3) selected - Dual execution path + memory tier decisions (when Pattern 4 / SC-01) - CAP-ID checklist complete for selected scenarios - Assembly template (T-01 / T-02 / T-03 / T-00) named - Agent identities + model tiers documented - Worker anti-pattern checklist completed (when CAP-060) - Observability trace documented (CAP-101) - PRF test IDs mapped to project test files - TASK-* rows mapped to golden task fixtures (when lane 4 in scope) - SC-02 × SC-05 rescan checklist completed (when both scenarios selected) - Skill coverage assessed - Decision recorded for SAO §17 via Write SAO.md (Activity 59)
20	Write SAO.md	DTA-20	Position in workflow: Terminal activity of Define Architecture (DTA) — order 20 of 20. Run …	Read the 'DTA-20 Write SAO.md' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. Position in workflow: Terminal activity of Define Architecture (DTA) — order 20 of 20. Run only after all prior DTA domain activities are complete (DTA-02 through DTA-17, and when applicable DTA-19 AI Agent Architecture and DTA-20 MCP Architecture). # Write SAO.md (System Architecture Overview) ## Objective Compile all architectural decisions from DTA-02 through DTA-17 (and optionally DTA-19 and DTA-20 if applicable) into a single, authoritative document: `docs/architecture/SAO.md`. ## Process ### 1. Gather All Decisions Collect recorded decisions from each domain activity: - DTA-02: Application Blocks - DTA-03: Integration & API Design - DTA-04: Code Organization - DTA-05: Data Architecture - DTA-06: Test Strategy - DTA-07: Performance & Scalability - DTA-08: Error Handling & Resilience - DTA-09: Infrastructure - DTA-10: CI/CD Pipeline - DTA-11: Release & Rollback - DTA-12: Observability - DTA-13: Config & Secrets - DTA-14: Security - DTA-15: Backup & Recovery - DTA-16: Developer Experience - DTA-17: Documentation Strategy - DTA-19: AI Agent Architecture (if applicable) - DTA-20: MCP Architecture (if applicable) ### 2. Write SAO.md Structure — add sections 17 and 18 after section 16: ``` ## 16. Documentation Strategy [Decision from DTA-17] ## 17. AI Agent Architecture [Decision from DTA-19 — skip section if no in-app agent] ## 18. MCP Architecture [Decision from DTA-20 — skip section if no MCP interface] ``` ### 3. Skill Gap Analysis Compile coverage reports from all domain activities into a single matrix: ``` Domain \| Covered Skills \| Gaps Application Blocks \| [list] \| [list] ... AI Agent Architecture \| [list] \| [list] MCP Architecture \| [list] \| [list] ``` ### 4. Review with User Present SAO.md for review. Get explicit approval before proceeding to Bootstrap Project. ### 5. Post-Implementation Updates The SAO is a living document. During and after implementation, update it with critical discoveries, retrospective corrections, and recurring patterns. Each update should reference the original DTA decision. ## Deliverables - SAO.md written at `docs/architecture/SAO.md` - All domain decisions (16 core + up to 2 optional: AI Agent, MCP) compiled - Skill coverage report included - Key decisions summary with rationale - User approval obtained - Ready to proceed to Define Software Process (DSP). DSP requires SAO.md to generate the AI IDE configuration — run DSP before BSP. When ESM, DTA, DSP, and BSP are all complete, proceed to BSP-08 for the Construction Handoff and mode selection.

Activities in Define Architecture