Artifacts - Junior Edda

Type

Required

Activity

Name	Type	Produced by	Required	Consumers	Actions
CICD Requirements (Release-Gated EB Reference)	Document	Review SAO & Define CICD Requirements Design & Deploy CICD	Required	2	Read the 'CICD Requirements (Release-Gated EB Reference)' artifact from playbook 'Junior Edda'. Type: Document. Required: true. # CI/CD Requirements ## Trigger Model Chosen: Release-gated (Huginn model) Rationale: Explicit semver control, avoids concurrent EB deploy races ```bash gh release create vX.Y.Z # sole production deploy trigger ``` Push to `main` does not run deploy jobs. ## Pipeline Architecture ``` gh release create vX.Y.Z → test (pytest) → build (ECR web + Docker Hub client image) → deploy-idle (SSM backup → EB deploy → idle smoke) → human review idle URL → make swap / promote.yml (production approval) → prod smoke (HTTPS /health/ revision) ``` ## Make Targets \| Target \| Description \| Added By \| \|--------\|-------------\|----------\| \| `make test` \| All tests \| BSP \| \| `make lint` \| Linting \| BSP \| \| `make swap` \| EB CNAME promote \| DCD \| \| `make eb-status` \| Show both EB envs \| DCD \| \| `make backup` \| Manual pre-migrate backup \| DCD \| ## GitHub Workflows \| File \| Trigger \| Purpose \| \|------\|---------\|---------\| \| `build-and-deploy.yml` \| release, workflow_dispatch \| test + build + deploy-idle \| \| `promote.yml` \| workflow_dispatch \| CNAME swap + prod smoke \| \| `infra.yml` (optional) \| push to `infra/**` \| CDK deploy only \| ## Environments \| Name \| URL \| Purpose \| \|------\|-----\|---------\| \| idle (dynamic) \| `http://{idle-cname}.elasticbeanstalk.com` \| Staging after deploy \| \| prod \| `https://app.example.com` \| Live traffic \| ## Image Tagging - Tag: `{branch-slug}-{short-sha}` (e.g. `v0.0.41-abc1234`) - EB VersionLabel: `v-{branch}-{sha}-r{run_number}` - Release revision: tag name (e.g. `v0.0.41`) stored as `{PROJECT}_GIT_REVISION` ## Quality Gates \| Gate \| Criteria \| \|------\|----------\| \| Test \| All pytest pass \| \| Backup \| S3 keys under `pre-migrate/{revision}/` \| \| Idle smoke \| HTTP 200, revision match \| \| Prod smoke \| HTTPS 200, revision match after swap \| ## Secrets \| Secret \| Purpose \| \|--------\|---------\| \| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` \| EB/ECR/S3/SSM (or OIDC) \| \| `GH_BUG_REPORT_TOKEN` \| Mapped to `GITHUB_TOKEN` on EB at deploy \| \| `DOCKERHUB_USERNAME` / `DOCKERHUB_TOKEN` \| Client MCP image \|
Implementation Plan Template	Document	Plan Feature Build Feature	Optional	8	Read the 'Implementation Plan Template' artifact from playbook 'Junior Edda'. Type: Document. Required: false. # Implementation Plan Template Artifact ID: 9 Type: Template Required: True ## Description # {FeatureName} - Implementation Plan Feature: {FeatureScreenID} {FeatureTitle} Feature File: `{FeatureFilePath}` GitHub Issues: {IssueNumbers} ({ScenarioIDs}) Branch: `feature/{feature-slug}` --- ## Context Map 3-5 file:line_range references for cold-start orientation. Read these first before touching any code. \| File \| Lines \| Why \| \|---\|---\|---\| \| `{FilePath1}` \| {N}-{M} \| {Why this area matters} \| \| `{FilePath2}` \| {N}-{M} \| {Why this area matters} \| \| `{FilePath3}` \| {N}-{M} \| {Why this area matters} \| ## Do Not Do Explicit out-of-scope guardrails. Violating these is a footprint_violation. - Do not touch {OutOfScopeArea1} — {Reason1} - Do not add {OutOfScopeChange2} — {Reason2} - Do not modify {OutOfScopeArea3} — {Reason3} ## SAO.md Sections That Apply Read these SAO.md sections before implementing. Check compliance before every checkpoint. - {SectionHeading1} (e.g., "3.2 Service Layer") - {SectionHeading2} (e.g., "4.1 MCP Tool Contracts") - {SectionHeading3} ## Log Story Script (Mandatory Section E) Each row is a beat the implementor must emit at INFO and prove with pytest caplog. Never defer logging to a final slice. ``` ## Log Story Script \| Where \| Beat \| Trigger \| Must include \| \|-------\|------\|---------\|--------------\| \| `{Class.method}` \| entry \| method called \| {key=} \| \| `{Class.method}` \| branch \| {reject_condition} \| {reason=} \| \| `{Class.method}` \| exit \| success/fail \| status= / id= \| ``` Beats: `entry \| config \| validation \| processing \| branch \| exit \| error`. ### Tests to Create — log story rows (Mandatory Section D addendum) \| Test \| Level \| Proves \| \|------\|-------\|--------\| \| `test_{feature}_log_story_happy` \| view/integration \| Log Story Script happy-path beats via caplog \| \| `test_{feature}_log_story_reject` \| view/integration \| Log Story Script reject-path beats via caplog \| ### Tests to Create — agent proof rows (Mandatory Section D addendum, when Section G populated) \| Test \| Level \| Proves \| \|------\|-------\|--------\| \| `test_{feature}_agent_story_happy` \| integration (`@agent_proof`) \| Agent Proof Table happy-path trace beats via `assert_agent_story` \| \| `test_{feature}_agent_story_reject` \| integration (`@agent_proof`) \| Agent Proof Table reject-path trace beats (adverse PRF rows) \| ### Dual checkpoint (when used under PIN) ```yaml checkpoint: command: "pytest ...::{behavior_test} -x" log_story_command: "pytest ...::{log_story_test} -x" agent_proof_command: "pytest ...::{agent_story_test} -m agent_proof -x" # when Section G populated ``` DoD: every declared command passes — behavior always; `log_story_command` when Section E has rows; `agent_proof_command` when Section G has rows. Omit undeclared keys. --- ## Agent Proof Table (Mandatory Section G) Skip with "Not applicable" if SAO §17 is N/A or this feature does not touch agent capabilities. ``` ## Agent Proof Table \| PRF ID \| Workflow \| Script path \| Trace beats to assert \| Adverse? \| \|--------\|----------\|-------------\|----------------------\|----------\| \| PRF-SC01-04 \| munin_chat \| tests/fixtures/llm_scripts/PRF-SC01-04/happy.json \| tools_blocked: list_entities \| yes \| \| PRF-SC01-04 \| munin_chat \| tests/fixtures/llm_scripts/PRF-SC01-04/reject_blocked.json \| tools_blocked: list_entities \| yes \| ``` Rules: - Map only PRF rows from SAO §17 / DTA-19 §13 that this feature affects. - Script paths under `tests/fixtures/llm_scripts/<prf-id>/` (`happy.json`, `reject_.json`). - Section D must name matching `test__agent_story_` tests for every selected PRF row. - Trace beats use artifact 56 Part 4.5 addendum vocabulary: workflow, tools, domain, board/plan. - TASK- golden tasks (lane 4) belong in SAO §17 / nightly eval — list in plan only when this slice introduces or changes a golden task fixture. - Reference: artifact 56 Part 4.5, skill Agent Integration Proof Patterns, rule `do-assert-agent-story`. --- ## Current State Assessment ### What Exists (Reusable) 1. {ComponentName1} - `{FilePath1}` - {ExistingFunctionality1} - {ExistingFunctionality2} - Decision: {ReuseDecision1} 2. {ComponentName2} - `{FilePath2}` - {ExistingFunctionality3} - {ExistingFunctionality4} - Decision: {ReuseDecision2} 3. {ComponentName3} - `{FilePath3}` - {ExistingFunctionality5} - Decision: {ReuseDecision3} ### What's Missing 1. {MissingComponent1} - {ScenarioID1} 2. {MissingComponent2} - {ScenarioID2} 3. {MissingComponent3} - {ScenarioID3} 4. {MissingComponent4} - {ScenarioID4} 5. {MissingComponent5} - {ScenarioID5} ### Issues to Fix 1. {Issue1}: {IssueDescription1} 2. {Issue2}: {IssueDescription2} 3. {Issue3}: {IssueDescription3} --- ## Clarification Questions ### Q1: {QuestionTopic1} Question: {QuestionText1} Answer: {AnswerText1} ### Q2: {QuestionTopic2} Question: {QuestionText2} Answer: {AnswerText2} ### Q3: {QuestionTopic3} Question: {QuestionText3} Answer: {AnswerText3} --- ## Implementation Plan ### Phase 0: Preparation - [ ] 0.1 Create feature branch ```bash git checkout -b feature/{feature-slug} ``` - [ ] 0.2 Read workflow files - Read BPE-02 / BPE-03 activity guidance - Read skill Pytest Log Story Assertions when Section E is populated --- ### Phase 1: {Phase1Title} ({ScenarioID1}, {ScenarioID2}) Scenario: {ScenarioDescription} GitHub Issue: {IssueNumber} #### Backend Changes - [ ] 1.1 {BackendTask1} - File: `{FilePath}` - Change: {ChangeDescription} - Test: `{TestFilePath}` - [ ] 1.2 {BackendTask2} - File: `{FilePath}` - Models: {ModelChanges} - Test: `{TestFilePath}` - [ ] 1.3 {BackendTask3} - File: `{FilePath}` - Services: {ServiceChanges} - Test: `{TestFilePath}` - [ ] 1.4 {BackendTask4} - File: `{FilePath}` - Views: {ViewChanges} - Test: `{TestFilePath}` - [ ] 1.5 {BackendTask5} - File: `{FilePath}` - URLs: {URLChanges} - Test: `{TestFilePath}` #### Frontend Changes - [ ] 1.6 {FrontendTask1} - File: `{TemplatePath}` - Template: {TemplateChanges} - Test: `{TestFilePath}` - [ ] 1.7 {FrontendTask2} - File: `{TemplatePath}` - HTMX: {HTMXChanges} - Test: `{TestFilePath}` - [ ] 1.8 {FrontendTask3} - File: `{TemplatePath}` - Semantic Attributes: {SemanticAttributes} - Test: `{TestFilePath}` #### Testing - [ ] 1.9 Unit tests for {Component} - File: `tests/unit/test_{component}.py` - Tests: {UnitTestList} - [ ] 1.10 Integration tests for {Scenario} - File: `tests/integration/test_{feature}_{scenario}.py` - Tests: {IntegrationTestList} - [ ] 1.11 View tests for {View} - File: `tests/integration/test_{view}_views.py` - Tests: {ViewTestList} - [ ] 1.12 Log story tests (caplog) - File: same as view/integration test module - Tests: `test_{feature}_log_story_happy`, `test_{feature}_log_story_reject` - Helper: `tests/support/log_story.py` → `assert_log_story` #### Commit - [ ] 1.13 Commit Phase 1 (behavior + log story green) ```bash git add . git commit -m "feat({scope}): {commit-message} {commit-body} Implements: {ScenarioID1}, {ScenarioID2} Closes: {IssueNumber}" ``` --- ### Phase 2: {Phase2Title} ({ScenarioID3}, {ScenarioID4}) Scenario: {ScenarioDescription} GitHub Issue: {IssueNumber} #### Backend Changes - [ ] 2.1 {BackendTask1} - File: `{FilePath}` - Change: {ChangeDescription} - [ ] 2.2 {BackendTask2} - File: `{FilePath}` - Change: {ChangeDescription} #### Frontend Changes - [ ] 2.3 {FrontendTask1} - File: `{TemplatePath}` - Change: {ChangeDescription} - [ ] 2.4 {FrontendTask2} - File: `{TemplatePath}` - Change: {ChangeDescription} #### Testing - [ ] 2.5 Unit tests - File: `{TestFilePath}` - Tests: {TestList} - [ ] 2.6 Integration tests - File: `{TestFilePath}` - Tests: {TestList} #### Commit - [ ] 2.7 Commit Phase 2 ```bash git commit -m "feat({scope}): {commit-message}" ``` --- ### Phase 3: {Phase3Title} ({ScenarioID5}) Scenario: {ScenarioDescription} GitHub Issue: {IssueNumber} #### Backend Changes - [ ] 3.1 {BackendTask} - File: `{FilePath}` - Change: {ChangeDescription} #### Frontend Changes - [ ] 3.2 {FrontendTask} - File: `{TemplatePath}` - Change: {ChangeDescription} #### Testing - [ ] 3.3 Integration tests - File: `{TestFilePath}` - Tests: {TestList} #### Commit - [ ] 3.4 Commit Phase 3 ```bash git commit -m "feat({scope}): {commit-message}" ``` --- ### Phase 4: E2E Testing & Finalization #### E2E Tests (Playwright) - [ ] 4.1 Create E2E test file - File: `tests/e2e/test_{feature}_journey.py` - Tests: Complete user journey from {StartPoint} to {EndPoint} - [ ] 4.2 Implement E2E scenarios - {E2EScenario1} - {E2EScenario2} - {E2EScenario3} #### Documentation - [ ] 4.3 Update README if needed - Document new feature - Update setup instructions - [ ] 4.4 Update feature file with completion markers - Mark implemented scenarios - Add implementation notes #### Final Checks - [ ] 4.5 Run full test suite ```bash pytest tests/ ``` - [ ] 4.6 Run linter ```bash make lint ``` - [ ] 4.7 Check test coverage ```bash pytest --cov={app} tests/ ``` - [ ] 4.8 Manual smoke test - Test all scenarios in browser - Verify UI/UX matches mockups #### Commit & PR - [ ] 4.9 Final commit ```bash git commit -m "test({scope}): add E2E tests for {feature}" ``` - [ ] 4.10 Push branch ```bash git push origin feature/{feature-slug} ``` - [ ] 4.11 Create Pull Request - Title: `{FeatureName} - {ScenarioIDs}` - Description: Link to feature file, implementation plan, and issues - Reviewers: {ReviewerNames} --- ## Definition of Done Checklist - [ ] All scenarios from feature file implemented - [ ] Unit tests: 100% pass rate - [ ] Integration tests: 100% pass rate - [ ] E2E tests: 100% pass rate - [ ] Log Story Script rows proven by caplog (`_log_story_` or `log_story_command`) - [ ] Agent Proof Table rows proven by `@agent_proof` tests (`_agent_story_` or `agent_proof_command`) when Section G populated - [ ] No deferred agent-proof slice - [ ] No deferred logging slice - [ ] Code coverage: {CoverageTarget}% minimum - [ ] Linter: 0 errors, 0 warnings - [ ] All `data-testid` attributes added for Playwright - [ ] All forms have proper validation - [ ] All error messages are user-friendly - [ ] All success messages are clear - [ ] Responsive design verified (mobile, tablet, desktop) - [ ] Accessibility: ARIA labels, keyboard navigation - [ ] Documentation updated - [ ] Feature file marked complete - [ ] GitHub issues closed - [ ] PR approved and merged --- ## Notes ### Architecture Decisions - {ArchitectureDecision1} - {ArchitectureDecision2} ### Technical Debt - {TechnicalDebt1} - {TechnicalDebt2} ### Future Enhancements - {FutureEnhancement1} - {FutureEnhancement2} --- ## Placeholder Reference - `{FeatureName}` - Feature name (e.g., "Authentication", "Playbook Management") - `{FeatureScreenID}` - Screen ID (e.g., FOB-AUTH-LOGIN-1) - `{ScenarioID}` - Scenario ID (e.g., AUTH-01, PLAYBOOKS-LIST-01) - `{FilePath}` - File path relative to project root - `{ComponentName}` - Component/module name - `{ModelChanges}` - Model changes description - `{ServiceChanges}` - Service changes description - `{ViewChanges}` - View changes description - `{URLChanges}` - URL routing changes - `{TemplateChanges}` - Template changes description - `{HTMXChanges}` - HTMX interaction changes - `{TestFilePath}` - Test file path - `{TestList}` - List of tests to implement - `{IssueNumber}` - GitHub issue number - `{feature-slug}` - Feature slug for branch name (lowercase, hyphenated) - `{scope}` - Commit scope (e.g., auth, playbooks, workflows) - `{commit-message}` - Commit message following Angular convention
INFRA Requirements (EB Reference)	Document	Review SAO & Define Infra Requirements Design & Deploy Cloud Infra	Required	1	Read the 'INFRA Requirements (EB Reference)' artifact from playbook 'Junior Edda'. Type: Document. Required: true. # Infrastructure Requirements ## AWS Region {region, e.g. us-east-1} ## Deployment Style Chosen: Elastic Beanstalk Rationale: Single web application, small team, prefer managed infrastructure over K8s ops Skill Reference: AWS Elastic Beanstalk Blue/Green Deployment ## Repo Layout - [ ] Separate `{project}-infra` repo - [x] `infra/` in application monorepo ## Services Required \| Service \| Purpose \| Configuration \| \|---------\|---------\|---------------\| \| VPC \| Network isolation \| Lookup existing or 2 public + 2 private subnets, NAT GW \| \| Elastic Beanstalk \| Managed Docker platform \| 2 envs: `{project}-prod`, `{project}-idle` \| \| ECR \| Container registry \| 1 repo for web image (reference existing if brownfield) \| \| S3 \| Deployment bundles + DB backups \| `elasticbeanstalk-{region}-{account}`, `{project}-db-backups-{account}` \| \| Route53 \| Public DNS \| CNAME → `{project}-prod.eba-….elasticbeanstalk.com` \| \| SES \| Transactional email \| Configuration set + verified domain (optional) \| \| SSM \| Pre-deploy backup \| `AmazonSSMManagedInstanceCore` on EB instance role \| ## Blue/Green Strategy - Two EB environments: `{project}-prod` (physical A), `{project}-idle` (physical B) - CNAME swap via `swap-environment-cnames` — prod is whichever env holds `{project}-prod` label - Route53 public CNAME points at fixed EB label — not ALB ARN - Deploy always to idle (resolved by CNAME inspection, not env name) ## Environment Variables (CI/CD) \| Var \| Example \| \|-----\|---------\| \| `EB_APP` \| `{project}` \| \| `EB_ENV_A` \| `{project}-prod` \| \| `EB_ENV_B` \| `{project}-idle` \| \| `EB_BUCKET` \| `elasticbeanstalk-{region}-{account}` \| \| `S3_BACKUP_BUCKET` \| `{project}-db-backups-{account}` \| ## Secrets Management \| Source \| What \| \|--------\|------\| \| `eb_live_platform_settings.json` \| Platform settings (exported from live, no secrets) \| \| `infra/.env` at `cdk deploy` \| `DATABASE_URL`, `DJANGO_SECRET_KEY`, API keys \| \| CI `deploy-idle.sh` \| `{PROJECT}_GIT_REVISION`, optional `GITHUB_TOKEN` from `GH_BUG_REPORT_TOKEN` \| ## Cost Estimate ~$65–95/month (2 EB envs + NAT + Route53 + S3) ## Security Requirements - Private subnets for EB instances - Security groups: ALB ↔ instances, EB ↔ RDS - IAM: EB service role, instance profile (ECR read, SES send, S3 backup, SSM) - CI IAM user scoped to ECR push, EB deploy, SSM SendCommand, S3 verify
SAO.md § Test Strategy	Document	Define Test Architecture Test Automation Framework	Optional	5	Read the 'SAO.md § Test Strategy' artifact from playbook 'Junior Edda'. Type: Document. Required: false. {"type": "Document", "is_required": true, "description": "SAO.md § Test Strategy — the authoritative Test Trophy, runner mapping (pytest / behave-django AT / Playwright E2E), coverage targets, quality gates, zero-bug policy, and zero-length feedback workflow. When SAO §17 applies, includes four agent test lanes (seeded DTA-06; fleshed TFK-01): control-plane proofs, deterministic shell, live contract eval, task performance quality. Seeded as broad strokes by DTA-06 / DTA-18; fleshed out by TFK-01 before BPE. Not a separate peer document under docs/architecture/. Consumed by TFK-02 through TFK-06 and by BPE-01 Plan Feature."}
Behave Configuration	Code	Bootstrap Test Harness Test Automation Framework	Required	3	Read the 'Behave Configuration' artifact from playbook 'Junior Edda'. Type: Code. Required: true. behave.ini and dual environment.py lifecycle files. Existing artifact: This ALTER targets Artifact #51 "Behave Configuration" (Code, required), currently produced by Activity #188 (Bootstrap Test Harness / TFK-02). Consumer activities already depend on it — this change updates the description to match the docs/features AT + tests/e2e layout (replacing obsolete `tests/acceptance/` / `features/at/` wording and clarifying dual environments). AT (docs/features/): `behave.ini` with `paths = docs/features`, `tags = ~@wip`. `docs/features/environment.py` wires Django test client / atomic scenario isolation (`manage.py behave --simple`). E2E (tests/e2e/): Invoked separately (`make test-e2e` → `manage.py behave tests/e2e/`). `tests/e2e/environment.py` wires Playwright + LiveServer, screenshots per step, optional `--base-url` / `--db-uri`. Do not nest E2E under AT. Do not use `tests/acceptance/` or `features/at/`. Prefer `@wip` for unimplemented AT scenarios (not `@e2e` exclusion for the AT path). Produced by TFK-02 (#188). Aligns with Workflow #54 Test Automation Framework and DTA-06 / SAO.md Test Strategy.
Estimation Reference Table	Document	Calibrate Reference Stories Estimate the Project	Required	4	Read the 'Estimation Reference Table' artifact from playbook 'Junior Edda'. Type: Document. Required: true. # FORGE Estimation Reference Table Version: 3.0 (FP/AFP pricing model added) Last updated: 2026-04-08 Status: SEED → PARTIALLY CALIBRATED (1 project, 8 acts measured) --- ## 1. SEED K-Token Baselines K-token cost per story point, by size tier. Derived for Django + HTMX + SQLite stack with AI-assisted single-dev workflow (PAF ≈ 1.4×). Adjust for other stacks via TCF. Two units — keep them separate: - SP (Story Points) — internal effort sizing. Used for token budget and duration estimates. Never shown to client. - FP (Function Points) — client-facing deliverable units. Used in the AFP pricing formula. Goes on the quote. \| Size \| SP (internal) \| FP weight (client) \| K min \| K expected \| K max \| Reference story \| \|------\|:-------------:\|:------------------:\|------:\|-----------:\|------:\|-----------------\| \| XS \| 0.5 \| 0.5 \| 12 \| 22 \| 36 \| Single HTMX fragment or read-only view \| \| S \| 1 \| 1 \| 25 \| 45 \| 72 \| Simple CRUD endpoint (reusing existing pattern) \| \| M \| 2 \| 2 \| 60 \| 100 \| 160 \| New model + service + repo + view + template \| \| L \| 5 \| 3 \| 155 \| 250 \| 410 \| Cross-cutting feature (auth, search, export) \| \| XL \| 8 \| 5 \| 275 \| 440 \| 720 \| Novel integration (external API, MCP server, async worker) \| Note: L and XL FP weights are lower than SP values because the client pays for delivered capability, not internal effort complexity. Complex cross-cutting work (auth, search) delivers 3 FP of value even if it takes 5 SP of effort. Calibration status: SEED (not yet statistically validated — requires ≥ 3 completed sprints with token logs) --- ## 2. AI Productivity Adjustment Factor (PAF) \| AI Tier \| Model class \| PAF range \| Notes \| \|----------\|----------------\|-----------\|-------\| \| Tier 1 \| Claude Sonnet 4+ \| 1.3–1.5× \| Primary coding model; context-rich sessions \| \| Tier 2 \| Claude Haiku 4+ \| 1.1–1.3× \| Fast iteration; lower context retention \| \| Baseline \| No AI / manual \| 1.0× \| Pure human baseline \| Applied as: `K_adjusted = K_seed / PAF` (fewer tokens needed because AI is more efficient) Default for Mimir stack: PAF = 1.4× (Tier 1, established codebase context) --- ## 3. Client Pricing Model — AFP Formula ``` AFP = Σ FP × Stack Factor × Org Factor Quote Total = AFP × $/FP ``` What the client sees: FP count, Stack Factor, Org Factor, $/FP rate, AFP total, and Total price. What the client never sees: tokens, K values, ECF, TCF, SP, or internal calibration data. ECF and TCF (Section 4 below) are internal multipliers that feed the $/FP calibration rate — they are not exposed on the quote. The Stack Factor and Org Factor encode the same real-world friction for the client but in commercially legible terms. --- ## 4. Stack Factor (Client-Facing) Stack Factor reflects the technical complexity and risk of the client's technology environment. Applied per-project. Base tier: \| Stack Factor \| Description \| \|:------------:\|-------------\| \| 0.85 \| Greenfield project, single clean modern stack, no legacy constraints \| \| 1.00 \| Standard single stack (Django+HTMX, Rails, Node/Express, FastAPI) \| \| 1.25 \| Two integrated stacks (e.g., React SPA + REST API backend) \| \| 1.50 \| Legacy codebase integration (strangler-fig, adapter patterns) \| \| 1.75 \| Multi-cloud or platform-constrained deployment (GCP + AWS, etc.) \| \| 2.00 \| Enterprise platform (Salesforce, SAP, ServiceNow, SharePoint) \| \| 2.50+ \| Government / highly regulated system (FedRAMP, ITAR, FISMA) \| Additive modifiers (apply on top of base tier): \| Condition \| Modifier \| \|-----------\|:--------:\| \| On-premises deployment required \| +0.10 \| \| Legacy system integration (data migration, adapters) \| +0.15 \| \| Multi-cloud architecture \| +0.15 \| \| Real-time requirements (WebSockets, event streaming) \| +0.10 \| \| Mobile (iOS and/or Android) in scope \| +0.20 \| Example: Standard stack (1.00) + legacy integration (+0.15) + on-premises (+0.10) = Stack Factor 1.25 --- ## 5. Org Factor (Client-Facing) Org Factor reflects the friction introduced by the client's organizational processes, approval chains, and compliance requirements. Applied per-project. \| Org Factor \| Description \| \|:----------:\|-------------\| \| 0.80 \| Startup (1–5 people, flat structure, one decision-maker, no formal process) \| \| 1.00 \| Small team / SME (5–20 people, basic sprint process, PM involved) \| \| 1.25 \| Mid-size organization (20–100, defined SDLC, multiple stakeholders) \| \| 1.50 \| Enterprise (100+, formal change management, legal/security review gates) \| \| 2.00 \| ITIL/ITSM shop (CAB approvals, change freeze windows, ticketed releases) \| \| 2.50 \| Regulated enterprise (SOX, PCI-DSS, HIPAA — audit trails, sign-off requirements) \| \| 3.50 \| Government / public sector (procurement gates, FISMA/FedRAMP, multi-agency review) \| --- ## 6. $/FP Calibration Rate The $/FP rate is the internal bridge between token cost and client pricing. It is derived from actual sprint data and is updated after each sprint close. \| Status \| $/FP Rate \| How Set \| \|--------\|:---------:\|---------\| \| SEED \| $250 \| Pre-calibration default. Derived from $3/MTok × avg K per FP (≈ 83K/FP at M size). Use until 3 sprints complete. \| \| CALIBRATED \| actual \| `$/FP_actual = total_api_cost_sprint / total_FP_delivered_sprint`. Weighted average over last 3–5 sprints. \| $/FP is never shown to the client. The client sees the AFP total and the total price. The $/FP rate is adjusted by finance/delivery after each sprint close via EST-08. Margin note: $/FP SEED rate of $250 assumes ~3× markup over raw API cost. Adjust markup policy to match your business model. --- ## 7. BSP / DSP Overhead FP Bootstrap (BSP) and Deploy Software Process (DSP) are quoted as a "Sprint 0 / Project Setup" line item on the client quote, separate from feature delivery FPs. FP weights for BSP activities (Sprint 0): \| Activity \| Size \| FP \| \|----------\|:----:\|---:\| \| BSP-01 Verify/Install Prerequisites \| XS \| 0.5 \| \| BSP-02 Initialize Repository \| XS \| 0.5 \| \| BSP-03 Scaffold Project Structure \| S \| 1.0 \| \| BSP-04 Initialize Runtimes/Dependencies \| S \| 1.0 \| \| BSP-05 Configure Dev Tooling \| M \| 2.0 \| \| BSP-06 Create Makefile \| M \| 2.0 \| \| BSP-07 Create Welcome Page/Verify \| S \| 1.0 \| \| BSP-08 Configure Observability/Logging \| M \| 2.0 \| \| BSP Total \| \| 10.0 FP \| FP weights for DSP activities (AI IDE configuration): \| Activity \| Size \| FP \| \|----------\|:----:\|---:\| \| DSP-01 Verify ESM Artifacts \| XS \| 0.5 \| \| DSP-02 Verify DTA Artifacts \| XS \| 0.5 \| \| DSP-03 Verify Architecture/Code Organization \| S \| 1.0 \| \| DSP-04 Choose Target AI IDE \| XS \| 0.5 \| \| DSP-05 Generate AI IDE Configuration \| M \| 2.0 \| \| DSP-06 Review and Commit \| XS \| 0.5 \| \| DSP Total \| \| 5.0 FP \| Combined Sprint 0 overhead: ~15 FP (before Stack × Org adjustment). On the client quote, show as: `Sprint 0 — Project Setup: 15 FP × Stack × Org × $/FP` --- ## 8. ECF / TCF Combined Multiplier — Internal (feeds $/FP calibration) > Internal use only. ECF/TCF determine the internal token cost per FP, which feeds the $/FP calibration rate. These factors are never shown to the client — the Stack Factor and Org Factor capture the same reality in client-legible terms. ### Mimir MVP Actuals ECF (Environmental Complexity Factor): \| Factor \| Description \| Rating \| Weight \| Contribution \| \|--------\|-------------\|-------:\|-------:\|-------------:\| \| E1 \| Familiarity with used model \| 4 \| 1.5 \| 6.0 \| \| E2 \| Application experience \| 2 \| 0.5 \| 1.0 \| \| E3 \| OO experience \| 4 \| 1.0 \| 4.0 \| \| E4 \| Lead analyst capability \| 4 \| 0.5 \| 2.0 \| \| E5 \| Motivation \| 5 \| 1.0 \| 5.0 \| \| E6 \| Stable requirements \| 4 \| 2.0 \| 8.0 \| \| E7 \| Part-time workers \| 5 \| -1.0 \| -5.0 \| \| E8 \| Difficult programming language \| 4 \| -1.0 \| -4.0 \| `ECF = 1.4 + (−0.03 × 17.0) = 0.89` AI extension (A1–A5 factors, sum = 17): `ECF_final = 0.89 × (1 − 0.08) = 0.82` TCF (Technical Complexity Factor): Sum of T1–T13 weighted ratings = 42. `TCF = 0.6 + (0.01 × 42) = 1.02` Combined multiplier: `0.82 × 1.02 = 0.87` ← favorable AI environment, use this for Mimir-like projects --- ## 9. Sizing Rules — v2 (Post-Calibration) ### v1 → v2 Changes The root cause of Mimir estimation errors was using scenario count as a proxy for implementation effort. Scenarios measure test breadth, not code complexity. \| Pattern \| v1 Rule \| v2 Rule \| Why changed \| \|---------\|---------\|---------\|-------------\| \| 1st CRUD entity of a type \| S → M \| S → M (unchanged) \| Correct — first instance is novel \| \| 2nd–Nth CRUD entity (reusing pattern) \| S → M \| XS → S \| Pattern reuse cuts effort dramatically \| \| Novel cross-cutting feature \| M → L \| M → L (unchanged) \| Cross-cutting features don't benefit from reuse \| \| Config / bootstrap (settings, URLs, base templates) \| S → M \| XS → S \| Code-light, config-heavy; was over-estimated in Auth/Setup (VF=0.39) \| \| External integration (API client, MCP server) \| M → L \| L → XL \| Integration uncertainty is real; MCP VF shows L underestimates \| \| Feature sizing by scenario count \| ❌ used \| ❌ never use \| 10 scenarios ≠ 10× effort vs 1 scenario \| ### Decision Tree for Sizing a Feature ``` Is this a completely new type of feature in the codebase? ├── YES → Is it cross-cutting or integration work? │ ├── YES (cross-cutting) → L → XL │ └── NO (new CRUD entity) → S → M └── NO → Does it reuse an established pattern (service/repo/template)? ├── YES → XS → S └── NO (new wrinkle on old pattern) → S → M ``` --- ## 10. Mimir MVP Calibration Results Measured from `main` branch, April 2026. LOC via `cloc`, 8 act groups. Calibration factor: 0.10 K tokens / LOC (anchored on Activities act). \| Act Group \| Est SP \| Est K exp (K) \| Actual LOC \| Token Proxy (K) \| VF \| Status \| \|-----------\|-------:\|--------------:\|-----------:\|----------------:\|----:\|--------\| \| Auth / Setup \| 3.0 \| 135 \| 1,765 \| 177 \| 1.30× \| ~accurate \| \| Playbooks \| 27.0 \| 1,790 \| 3,372 \| 337 \| 0.19× \| ❌ over-estimated 5× \| \| Workflows \| 13.0 \| 910 \| 2,996 \| 300 \| 0.33× \| ❌ over-estimated 3× \| \| Activities \| 6.0 \| 280 \| 3,388 \| 339 \| 1.21× \| ✅ calibration anchor \| \| Artifacts \| 15.0 \| 720 \| 2,654 \| 265 \| 0.37× \| ❌ over-estimated 2.7× \| \| Agents \| 3.5 \| 113 \| 1,919 \| 192 \| 1.70× \| ⚠ slightly under \| \| Skills \| 6.0 \| 235 \| 1,762 \| 176 \| 0.75× \| ~accurate \| \| MCP \| 24.0 \| 1,250 \| 3,529 \| 353 \| 0.28× \| ❌ over-estimated 3.6× \| \| TOTAL \| 114.5 \| 6,433 \| 25,885 \| 2,588 \| 0.40× \| \| Summary: Overall estimate was ~2.5× too high in SP terms. K-per-SP baselines appear reasonable; the problem was SP sizing. ### Root Cause The Mimir estimation sized acts by counting scenarios per feature file (10 scenarios → large = L or XL). This is wrong because: 1. Pattern reuse was ignored. Playbooks, Activities, Workflows, Artifacts all implement the same Django pattern (Model + Admin + Repository + Service + View + Template + FAT). The 2nd–4th entity takes a fraction of the effort of the 1st. 2. Scenario count ≠ implementation effort. A feature with 10 edge-case scenarios tests one endpoint from many angles. It doesn't take 10× more code than a 1-scenario feature. 3. K baselines are largely correct. Activities VF = 1.21 and Auth/Setup VF = 1.30 confirm the K values for genuinely novel work are in the right range. --- ## 11. Sprint Actuals History _Populate after each sprint close (EST-08)._ \| Sprint \| Planned SP \| Actual SP \| Planned K \| Actual K (from token log) \| VF \| Date \| \|--------\|:----------:\|:---------:\|:---------:\|:-------------------------:\|:--:\|------\| \| — \| — \| — \| — \| — \| — \| — \| Calibration threshold: 3+ completed sprints with token logs → update status from SEED → CALIBRATED. --- ## 12. COCOMO Convergence (Schedule Uncertainty by Phase) \| Phase \| Min bound \| Max bound \| Source \| \|-------\|:---------:\|:---------:\|--------\| \| Initial concept \| ×0.25 \| ×4.0 \| McConnell 1996, Table 5-2 \| \| Approved product definition \| ×0.5 \| ×2.0 \| ibid \| \| Requirements complete \| ×0.67 \| ×1.5 \| ibid \| \| Architecture complete \| ×0.80 \| ×1.25 \| ibid \| \| Detailed design complete \| ×0.90 \| ×1.10 \| ibid \| Mimir MVP ran EST at "Architecture complete" → P10/P90 range: ×0.80 to ×1.25 of P50. --- ## 13. McConnell Schedule Formula ``` Optimal schedule (calendar months) = 3.0 × (effort in person-months)^(1/3) ``` For AI-assisted single developer: `person-months = K_total / (throughput_K_per_month)` Default Mimir throughput: 1,500 K tokens/day × 20 working days = 30,000 K/month. Example at P50 = 18,200 K: `person-months = 18,200 / 30,000 = 0.61` `schedule = 3.0 × 0.61^(1/3) = 3.0 × 0.85 = 2.6 months ≈ 12 working days` ← matches simulation --- ## 14. BPE Artifact K Ranges (Django + HTMX Stack) Token cost ranges for individual BPE artifacts, independent of SP sizing. \| Artifact \| Small (K) \| Medium (K) \| Large (K) \| \|----------\|----------:\|-----------:\|----------:\| \| Django Model + Admin \| 8 \| 15 \| 28 \| \| Repository methods \| 5 \| 10 \| 20 \| \| Service layer \| 8 \| 18 \| 35 \| \| Django View + URL \| 6 \| 12 \| 22 \| \| Unit + Integration Tests \| 10 \| 20 \| 40 \| \| Django Template + HTMX \| 8 \| 16 \| 30 \| \| Feature Acceptance Tests (FAT) \| 8 \| 15 \| 28 \| \| DoD checklist \| 3 \| 6 \| 12 \| \| E2E + PR \| 6 \| 12 \| 22 \| \| Implementation Plan \| 5 \| 8 \| 15 \| Use these ranges for Level 2 detailed estimates (EST-06). Sum artifact estimates per feature and use PERT formula. --- ## 15. Notes and Open Questions - [ ] Validate K baselines once 3 sprints have actual token logs (target: CALIBRATED status) - [ ] Measure "pattern reuse discount" empirically: track tokens for 1st vs 2nd CRUD entity of same type - [ ] Check if LOC proxy 0.10 K/LOC holds for non-Django stacks (React, FastAPI, etc.) - [ ] The "17×" overestimate figures from pre-calibration analysis need reconciliation with 0.10 K/LOC factor — likely a different baseline was used (raw session tokens vs LOC proxy)
Helm Chart Template	Template	Create Helm Chart & Values Design & Deploy CICD	Required	5	Read the 'Helm Chart Template' artifact from playbook 'Junior Edda'. Type: Template. Required: true. # Artifact: Helm Chart Template Workflow: DCD — Design & Deploy CICD Purpose: Reference Helm chart structure for application deployment ## Chart Structure ``` deploy/helm/{project}/ ├── Chart.yaml ← Chart metadata ├── values.yaml ← Default values (production-like) ├── values-local.yaml ← Local K8s overrides (1 replica, no ECR) ├── values-blue.yaml ← Blue namespace overrides ├── values-green.yaml ← Green namespace overrides └── templates/ ├── _helpers.tpl ← Template helper functions ├── deployment.yaml ← Deployment manifest ├── service.yaml ← Service manifest ├── configmap.yaml ← ConfigMap manifest ├── secret.yaml ← Secret manifest (template only) └── ingress.yaml ← (optional) Ingress/ALB manifest ``` ## Chart.yaml ```yaml apiVersion: v2 name: {project} description: Helm chart for {project} type: application version: 0.1.0 appVersion: "0.1.0" ``` ## values.yaml (defaults) ```yaml replicaCount: 2 image: repository: "{account}.dkr.ecr.{region}.amazonaws.com/{project}" tag: "latest" pullPolicy: IfNotPresent service: type: ClusterIP port: 80 targetPort: 8000 resources: requests: cpu: 250m memory: 256Mi limits: cpu: 500m memory: 512Mi config: LOG_LEVEL: "INFO" ENVIRONMENT: "production" healthCheck: path: /health port: 8000 livenessInitialDelay: 15 readinessInitialDelay: 5 ``` ## values-local.yaml ```yaml replicaCount: 1 namespace: local image: repository: "{project}" tag: "local" pullPolicy: Never resources: requests: cpu: 100m memory: 128Mi limits: cpu: 250m memory: 256Mi config: ENVIRONMENT: "local" LOG_LEVEL: "DEBUG" ``` ## values-blue.yaml ```yaml namespace: blue config: ENVIRONMENT: "blue" ``` ## values-green.yaml ```yaml namespace: green config: ENVIRONMENT: "green" ``` ## Deployment Commands ```bash # Local helm upgrade --install {project} deploy/helm/{project} \ -f deploy/helm/{project}/values-local.yaml \ --namespace local --create-namespace # Blue helm upgrade --install {project} deploy/helm/{project} \ -f deploy/helm/{project}/values-blue.yaml \ --set image.tag=$(git rev-parse --short HEAD) \ --namespace blue --create-namespace --wait # Green helm upgrade --install {project} deploy/helm/{project} \ -f deploy/helm/{project}/values-green.yaml \ --set image.tag=$(git rev-parse --short HEAD) \ --namespace green --create-namespace --wait ``` ## Conventions - `values.yaml` = production-like defaults (always merged first) - Per-env files only override what differs (namespace, config, resources) - Image tag set at deploy time via `--set image.tag=...` - `--wait` flag in CI/CD ensures deployment health before proceeding - Secrets: never stored in values files; use `kubectl create secret` or external secrets
Infra Repo Scaffold	Template	Scaffold Infra Repo & CDK Project Design & Deploy Cloud Infra	Required	6	Read the 'Infra Repo Scaffold' artifact from playbook 'Junior Edda'. Type: Template. Required: true. # Artifact: Infra Repo Scaffold Workflow: DCI — Design & Deploy Cloud Infra Purpose: Reference directory structure for the infrastructure repository ## Repository Structure ``` {project}-infra/ ├── app.py ← CDK entry point (imports and wires stacks) ├── cdk.json ← CDK config (account, region, context) ├── requirements.txt ← Python deps: aws-cdk-lib, constructs, boto3, pytest ├── Makefile ← Infra operations (deploy, destroy, traffic-switch, etc.) ├── README.md ← Quick start, architecture overview, make targets ├── .github/ │ └── workflows/ │ └── infra.yml ← GH Actions: deploy on push, manual switch/rollback ├── stacks/ │ ├── __init__.py │ ├── vpc_stack.py ← VPC, subnets, NAT Gateway, security groups │ ├── eks_stack.py ← EKS cluster, node group, ECR repo, namespaces │ └── dns_stack.py ← Route53 hosted zone, prod/idle DNS records ├── scripts/ │ └── traffic_switch.py ← DNS weight switcher (switch/rollback/status) ├── tests/ │ ├── __init__.py │ ├── test_vpc_stack.py ← CDK snapshot/assertion tests for VPC │ ├── test_eks_stack.py ← CDK tests for EKS + ECR │ └── test_dns_stack.py ← CDK tests for Route53 ├── cdk.out/ ← (gitignored) synthesized CloudFormation templates └── .traffic_state.json ← (gitignored) last known traffic state for rollback ``` ## Key Files ### app.py CDK entry point that imports all stacks and wires dependencies: - VpcStack (no dependencies) - EksStack (depends on VpcStack.vpc) - DnsStack (no stack dependencies, but logically follows EKS) ### Makefile Targets ``` make help — Show all targets make provision — Install CDK + Python deps make synth — Synthesize CloudFormation (dry run) make deploy — Deploy all stacks make destroy — Destroy all stacks (DANGEROUS) make status — Show stack status make traffic-switch — Swap prod/idle DNS make traffic-rollback — Revert last switch make traffic-status — Show current routing make test — Run CDK tests ``` ### .gitignore Additions ``` cdk.out/ .traffic_state.json .venv/ __pycache__/ *.pyc ``` ## Conventions - Stack names: `{Project}VpcStack`, `{Project}EksStack`, `{Project}DnsStack` - All AWS resources tagged with `project={project}`, `environment=shared`, `managed-by=cdk` - CDK context for environment-specific values (account, region, domain) - Tests use CDK assertions (Template.from_stack)
User Journey	Document	Define User Journey Envision the System	Required	9	Read the 'User Journey' artifact from playbook 'Junior Edda'. Type: Document. Required: true. OUTPUT: docs/features/user_journey.md FORMAT: Complete user journey narrative with personas, Acts, screen descriptions following CRUDLF pattern TEMPLATE: See .windsurf/workflows/FeatureFactory/ESM/artifacts/user_journey_template.md for exact format with placeholders for: - Personas (name, role, description) - System architecture notes - Acts with screen IDs following pattern: {PROJECT}-{ENTITY}-{OPERATION}-{VERSION} - CRUDLF screens: LIST+FIND (entry), CREATE, VIEW, EDIT, DELETE - Layout details, form fields, validation rules, success/error states - Navigation flow summary
User Journey Template	Template	Define User Journey Envision the System	Required	2	Read the 'User Journey Template' artifact from playbook 'Junior Edda'. Type: Template. Required: true. # {ProjectName} User Journey ## Personas {PersonaName} - {PersonaRole} {PersonaDescription} {PersonaName2} - {PersonaRole2} {PersonaDescription2} --- ## System Architecture Note {SystemName}: {SystemDescription} - Component 1: {ComponentDescription} - Component 2: {ComponentDescription} Domain Model Notes: - Core Entities: {EntityList} - Key Relationships: {RelationshipDescription} --- ## ⚠️ Critical Architectural Principle {PrincipleName} {PrincipleDescription} Example: - {ExampleScenario} This separation ensures: - {Benefit1} - {Benefit2} - {Benefit3} --- ## Journey: {JourneyTitle} ### Act {ActNumber}: {ActTitle} Context: {ActContext} Pattern: {Entity} follows the standard CRUDLF pattern with LIST+FIND as the entry point. #### Screen: {ScreenID} {PersonaName} {ActionDescription}. The {ScreenName} appears: Layout: - Header: "{EntityName}" with count badge (e.g., "{EntityName} (3)") - Top Actions: - [Create New {EntityName}] button (primary action, bold blue) - [Additional Action] button - Search & Filter Section: - Search box: "Find {entity}..." (searches {fields}) - Filters: {Filter1}, {Filter2}, {Filter3} - [Clear Filters] button - {EntityName} Table with columns: - {Column1} \| {Column2} \| {Column3} \| Actions - Sort by any column - Row Actions (dropdown menu per {entity}): - [View] - Opens {ScreenID}-VIEW_{ENTITY} - [Edit] - Opens {ScreenID}-EDIT_{ENTITY} - [Delete] - Opens {ScreenID}-DELETE_{ENTITY} modal - [...More] - Additional actions - Empty State (if no {entity}): - Illustration: {IllustrationDescription} - "No {entity} yet" - "{CallToActionMessage}" - [Action Buttons] - Pagination: Shows 20 per page with page controls Example Data: - "{ExampleRow1}" \| {Data} \| {Data} \| {Status} - "{ExampleRow2}" \| {Data} \| {Data} \| {Status} {PersonaName} sees {UserObservation}. --- ### Act {ActNumber}: {ActTitle} - CREATE_{ENTITY} #### Screen: {ScreenID} {PersonaName} clicks [Create New {EntityName}]. The create form appears: Form Fields: - {FieldName} (required, text input) - Placeholder: "{ExampleValue}" - Validation: {ValidationRule} - {FieldName2} (optional, dropdown) - Options: {Option1}, {Option2}, {Option3} - {FieldName3} (required, textarea) - Placeholder: "{ExampleValue}" - Max length: {MaxLength} characters Actions: - [Save] button (primary, blue) - Creates {entity} and redirects to VIEW - [Cancel] button (secondary, gray) - Returns to LIST without saving Validation: - Required fields marked with asterisk () - Real-time validation on blur - Error messages appear below fields in red - Save button disabled until all required fields valid {PersonaName} fills in the form and clicks [Save]. Success: - Green toast: "{EntityName} '{Name}' created successfully" - Redirects to {ScreenID}-VIEW_{ENTITY} Error: - Red toast: "Failed to create {entity}: {ErrorMessage}" - Form remains open with error details --- ### Act {ActNumber}: {ActTitle} - VIEW_{ENTITY} #### Screen: {ScreenID} {PersonaName} views {entity} details: Layout: - Header: {EntityName} name with status badge - Metadata Section: - Created: {Date} by {Author} - Last modified: {Date} by {Editor} - Status: {StatusBadge} - Details Section: - {Field1}: {Value1} - {Field2}: {Value2} - {Field3}: {Value3} - Related Items* (if applicable): - {RelatedEntity1} ({Count}) - {RelatedEntity2} ({Count}) - Actions: - [Edit] button - Opens EDIT_{ENTITY} - [Delete] button - Opens DELETE_{ENTITY} modal - [Additional Action] button --- ### Act {ActNumber}: {ActTitle} - EDIT_{ENTITY} #### Screen: {ScreenID} {PersonaName} clicks [Edit]. The edit form appears with current values pre-filled: Form Fields: (Same as CREATE form but pre-populated) Actions: - [Save Changes] button (primary, blue) - [Cancel] button (secondary, gray) {PersonaName} modifies fields and clicks [Save Changes]. Success: - Green toast: "{EntityName} updated successfully" - Returns to VIEW_{ENTITY} --- ### Act {ActNumber}: {ActTitle} - DELETE_{ENTITY} #### Screen: {ScreenID} (Modal) {PersonaName} clicks [Delete]. A confirmation modal appears: Modal Content: - Title: "Delete {EntityName}?" - Message: "Are you sure you want to delete '{Name}'? This action cannot be undone." - Warning (if applicable): "This will also delete {RelatedCount} related {RelatedEntity}." - Actions: - [Delete] button (danger, red) - [Cancel] button (secondary, gray) {PersonaName} clicks [Delete]. Success: - Green toast: "{EntityName} deleted successfully" - Redirects to LIST+FIND - {Entity} removed from table Error: - Red toast: "Failed to delete {entity}: {ErrorMessage}" - Modal closes, returns to VIEW --- ## Navigation Flow Summary ``` LIST+FIND → CREATE → VIEW ↓ ↓ FILTER EDIT → VIEW ↓ ↓ SEARCH DELETE → LIST ``` ## Screen ID Conventions - LIST+FIND: `{PROJECT}-{ENTITY}-LIST+FIND-{VERSION}` - CREATE: `{PROJECT}-{ENTITY}-CREATE_{ENTITY}-{VERSION}` - VIEW: `{PROJECT}-{ENTITY}-VIEW_{ENTITY}-{VERSION}` - EDIT: `{PROJECT}-{ENTITY}-EDIT_{ENTITY}-{VERSION}` - DELETE: `{PROJECT}-{ENTITY}-DELETE_{ENTITY}-{VERSION}` ## Placeholder Reference - `{ProjectName}` - Name of the project - `{PersonaName}` - User persona name - `{PersonaRole}` - User persona role/title - `{EntityName}` - Name of the entity (singular, capitalized) - `{entity}` - Name of the entity (singular, lowercase) - `{ScreenID}` - Unique screen identifier - `{ActNumber}` - Act number (0-15) - `{ActTitle}` - Title of the act - `{FieldName}` - Form field name - `{ValidationRule}` - Validation rule description
CDK Stack Templates	Code	Build VPC & Networking Stack Design & Deploy Cloud Infra	Required	4	Read the 'CDK Stack Templates' artifact from playbook 'Junior Edda'. Type: Code. Required: true. #!/usr/bin/env python3 """ CDK Stack Templates — FeatureFactory DCI Workflow Skeleton implementations for VPC, EKS+ECR, and Route53 CDK stacks. Copy these into your infra repo's stacks/ directory and adapt to your project's INFRA_REQUIREMENTS.md. Usage: 1. Copy each class to its own file in stacks/ 2. Replace {project} placeholders with your project name 3. Update context values in cdk.json 4. Run `make synth` to verify """ import aws_cdk as cdk from aws_cdk import ( Stack, RemovalPolicy, aws_ec2 as ec2, aws_eks as eks, aws_ecr as ecr, aws_iam as iam, aws_route53 as route53, ) from constructs import Construct # ============================================================================== # VPC Stack — stacks/vpc_stack.py # ============================================================================== class VpcStack(Stack): """ Network foundation: VPC with public/private subnets and NAT Gateway. Outputs: self.vpc — ec2.Vpc instance (consumed by EksStack) self.eks_sg — Security group for EKS worker nodes """ def __init__(self, scope: Construct, id: str, kwargs) -> None: super().__init__(scope, id, kwargs) # VPC with 2 AZs self.vpc = ec2.Vpc( self, "Vpc", max_azs=2, nat_gateways=1, # 1 shared for cost; set to 2 for HA in production subnet_configuration=[ ec2.SubnetConfiguration( name="Public", subnet_type=ec2.SubnetType.PUBLIC, cidr_mask=24, ), ec2.SubnetConfiguration( name="Private", subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS, cidr_mask=24, ), ], ) # Security group for EKS worker nodes self.eks_sg = ec2.SecurityGroup( self, "EksNodeSg", vpc=self.vpc, description="Security group for EKS worker nodes", allow_all_outbound=True, ) # Tag all resources cdk.Tags.of(self).add("managed-by", "cdk") cdk.Tags.of(self).add("stack", "vpc") # ============================================================================== # EKS + ECR Stack — stacks/eks_stack.py # ============================================================================== class EksStack(Stack): """ Compute layer: EKS cluster with managed node group and ECR repository. Requires: vpc — ec2.Vpc from VpcStack Outputs: self.cluster — eks.Cluster instance self.ecr_repo — ecr.Repository instance """ def __init__(self, scope: Construct, id: str, vpc: ec2.Vpc, kwargs) -> None: super().__init__(scope, id, kwargs) # EKS Cluster self.cluster = eks.Cluster( self, "Cluster", vpc=vpc, version=eks.KubernetesVersion.V1_29, default_capacity=0, endpoint_access=eks.EndpointAccess.PUBLIC_AND_PRIVATE, ) # Managed Node Group self.cluster.add_nodegroup_capacity( "WorkerNodes", instance_types=[ec2.InstanceType("t3.medium")], min_size=2, max_size=4, desired_size=2, disk_size=50, subnets=ec2.SubnetSelection( subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS ), ) # ECR Repository self.ecr_repo = ecr.Repository( self, "AppRepo", repository_name="{project}", # TODO: replace with actual project name removal_policy=RemovalPolicy.RETAIN, lifecycle_rules=[ ecr.LifecycleRule( max_image_count=20, description="Keep last 20 images", ) ], ) # Create blue/green namespaces for ns in ["blue", "green"]: self.cluster.add_manifest( f"{ns}-namespace", { "apiVersion": "v1", "kind": "Namespace", "metadata": {"name": ns}, }, ) cdk.Tags.of(self).add("managed-by", "cdk") cdk.Tags.of(self).add("stack", "eks") # ============================================================================== # DNS Stack — stacks/dns_stack.py # ============================================================================== class DnsStack(Stack): """ DNS layer: Route53 hosted zone for blue/green traffic switching. Context: domain — Base domain (e.g., "app.example.com") Outputs: self.zone — route53.HostedZone instance """ def __init__(self, scope: Construct, id: str, kwargs) -> None: super().__init__(scope, id, kwargs) domain = self.node.try_get_context("domain") # Hosted zone self.zone = route53.HostedZone( self, "Zone", zone_name=domain, ) # Note: Weighted records for prod/idle are managed by # scripts/traffic_switch.py, not by CDK. CDK only creates the zone. # This avoids CDK drift when the switch script modifies records. cdk.Tags.of(self).add("managed-by", "cdk") cdk.Tags.of(self).add("stack", "dns") # ============================================================================== # App Entry Point — app.py # ============================================================================== def create_app(): """ CDK app entry point. Wire stacks with dependencies. Usage in app.py: from cdk_stack_templates import create_app create_app() """ app = cdk.App() env = cdk.Environment( account=app.node.try_get_context("account"), region=app.node.try_get_context("region"), ) vpc = VpcStack(app, "VpcStack", env=env) eks = EksStack(app, "EksStack", vpc=vpc.vpc, env=env) dns = DnsStack(app, "DnsStack", env=env) # Explicit dependencies eks.add_dependency(vpc) app.synth() if __name__ == "__main__": create_app()
Estimation Template (Excel)	Document	Size Scenarios (Level 1 SWAG) Estimate the Project	Required	4
IA Guidelines	Document	Define Information Architecture Envision the System	Required	7	Read the 'IA Guidelines' artifact from playbook 'Junior Edda'. Type: Document. Required: true. OUTPUT: docs/ux/IA_guidelines.md FORMAT: Design system specification based on Bootstrap 5.3+ TEMPLATE: See .windsurf/workflows/FeatureFactory/ESM/artifacts/ia_guidelines_template.md for complete structure including: - Design Tokens (colors, typography, spacing, shadows) - Skeleton & Layout (grid system, containers, responsive breakpoints) - Visual Design (color palette, typography scale, iconography with Font Awesome Pro) - Component Kit (atoms, molecules, organisms following Atomic Design) - Behavior & Interactions (hover states, animations, accessibility) - Flow & User Experience (navigation patterns, form validation, error handling) - Data & State Patterns (loading states, empty states, error states)
IA Guidelines Template	Template	Define Information Architecture Envision the System	Required	2	Read the 'IA Guidelines Template' artifact from playbook 'Junior Edda'. Type: Template. Required: true. # {ProjectName} Information Architecture Guidelines ## Document Overview This document defines the Information Architecture, Design System, and UI patterns for the {ProjectName} application. We rely heavily on Bootstrap 5.3+ as our foundational framework, extending it with custom tokens and components where needed. Philosophy: Leverage Bootstrap's conventions, utilities, and component patterns as the first choice. Customize only when necessary for brand identity or specific user experience requirements. --- ## Table of Contents 1. [Design System Foundation](#design-system-foundation) 2. [Skeleton & Layout](#skeleton--layout) 3. [Visual Design](#visual-design) 4. [Component Kit (Atomic Design)](#component-kit-atomic-design) 5. [Behavior & Interactions](#behavior--interactions) 6. [Flow & User Experience](#flow--user-experience) 7. [Data & State Patterns](#data--state-patterns) --- ## Design System Foundation ### 1. Design Tokens We extend Bootstrap's native CSS variables with {ProjectName}-specific tokens. All tokens follow Bootstrap's naming convention for consistency. #### Color Tokens Base Bootstrap Colors (use as-is): ```css /* Primary palette - Bootstrap defaults / --bs-primary: {PrimaryColor}; --bs-secondary: {SecondaryColor}; --bs-success: #198754; --bs-info: #0dcaf0; --bs-warning: #ffc107; --bs-danger: #dc3545; --bs-light: #f8f9fa; --bs-dark: #212529; / Grayscale / --bs-gray-100: #f8f9fa; --bs-gray-200: #e9ecef; --bs-gray-300: #dee2e6; --bs-gray-400: #ced4da; --bs-gray-500: #adb5bd; --bs-gray-600: #6c757d; --bs-gray-700: #495057; --bs-gray-800: #343a40; --bs-gray-900: #212529; ``` {ProjectName} Custom Colors: ```css / Dashboard/feature-specific colors / --{project}-color-1: {CustomColor1}; --{project}-color-2: {CustomColor2}; --{project}-color-3: {CustomColor3}; / Background colors / --{project}-bg-body: #f5f5f5; --{project}-bg-surface: #ffffff; --{project}-bg-elevated: #ffffff; ``` #### Spacing Tokens Use Bootstrap's spacing scale* (0.25rem increments): ```css /* Bootstrap spacing multiplier: 1 = 0.25rem = 4px / --bs-spacer: 1rem; / 16px base / / Usage via utility classes / .m-0 / margin: 0 / .m-1 / margin: 0.25rem (4px) / .m-2 / margin: 0.5rem (8px) / .m-3 / margin: 1rem (16px) / .m-4 / margin: 1.5rem (24px) / .m-5 / margin: 3rem (48px) / ``` {ProjectName} Custom Spacing: ```css / Card spacing / --{project}-card-padding: 1.25rem; --{project}-card-gap: 1.5rem; / Section spacing / --{project}-section-gap: 2rem; --{project}-content-max-width: 1200px; ``` #### Typography Tokens Bootstrap Font Stack* (use as-is): ```css --bs-font-sans-serif: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; --bs-font-monospace: SFMono-Regular, Menlo, Monaco, Consolas, "Courier New", monospace; /* Font sizes - Bootstrap scale / --bs-body-font-size: 1rem; --bs-h1-font-size: 2.5rem; --bs-h2-font-size: 2rem; --bs-h3-font-size: 1.75rem; --bs-h4-font-size: 1.5rem; --bs-h5-font-size: 1.25rem; --bs-h6-font-size: 1rem; ``` --- ## Skeleton & Layout ### Navigation Structure Primary Navigation: - {NavigationItem1} - {NavigationItem2} - {NavigationItem3} - {NavigationItem4} Navigation Pattern: Bootstrap navbar with dropdown menus for entity groups. ```html <nav class="navbar navbar-expand-lg navbar-dark bg-dark"> <div class="container-fluid"> <a class="navbar-brand" href="/">{ProjectName}</a> <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNav"> <span class="navbar-toggler-icon"></span> </button> <div class="collapse navbar-collapse" id="navbarNav"> <ul class="navbar-nav"> <li class="nav-item"><a class="nav-link" href="/{entity1}/">{Entity1}</a></li> <li class="nav-item"><a class="nav-link" href="/{entity2}/">{Entity2}</a></li> <li class="nav-item"><a class="nav-link" href="/{entity3}/">{Entity3}</a></li> </ul> </div> </div> </nav> ``` ### Page Layout Pattern Standard Page Structure: ```html <div class="container-fluid"> <!-- Page Header --> <div class="row mb-4"> <div class="col"> <h1>{PageTitle}</h1> <p class="text-muted">{PageDescription}</p> </div> </div> <!-- Main Content --> <div class="row"> <div class="col-lg-12"> {MainContent} </div> </div> </div> ``` --- ## Component Kit (Atomic Design) ### Atoms #### Buttons Primary Actions: ```html <button class="btn btn-primary" data-bs-toggle="tooltip" title="{TooltipText}"> <i class="fa-solid fa-{icon}"></i> {ButtonText} </button> ``` Secondary Actions: ```html <button class="btn btn-secondary" data-bs-toggle="tooltip" title="{TooltipText}"> <i class="fa-solid fa-{icon}"></i> {ButtonText} </button> ``` Danger Actions: ```html <button class="btn btn-danger" data-bs-toggle="tooltip" title="{TooltipText}"> <i class="fa-solid fa-{icon}"></i> {ButtonText} </button> ``` #### Form Inputs Text Input: ```html <div class="mb-3"> <label for="{fieldId}" class="form-label">{FieldLabel} <span class="text-danger"></span></label> <input type="text" class="form-control" id="{fieldId}" name="{fieldName}" placeholder="{PlaceholderText}" required data-testid="{entity}-{field}-input"> <div class="invalid-feedback">{ErrorMessage}</div> </div> ``` Textarea: ```html <div class="mb-3"> <label for="{fieldId}" class="form-label">{FieldLabel}</label> <textarea class="form-control" id="{fieldId}" name="{fieldName}" rows="4" placeholder="{PlaceholderText}" data-testid="{entity}-{field}-textarea"></textarea> </div> ``` Select Dropdown: ```html <div class="mb-3"> <label for="{fieldId}" class="form-label">{FieldLabel}</label> <select class="form-select" id="{fieldId}" name="{fieldName}" data-testid="{entity}-{field}-select"> <option value="">{DefaultOption}</option> <option value="{value1}">{Option1}</option> <option value="{value2}">{Option2}</option> </select> </div> ``` ### Molecules #### Card Component ```html <div class="card shadow-sm" data-testid="{entity}-card"> <div class="card-header"> <h5 class="card-title mb-0">{CardTitle}</h5> </div> <div class="card-body"> {CardContent} </div> <div class="card-footer"> {CardActions} </div> </div> ``` #### Table Component ```html <div class="table-responsive"> <table class="table table-hover" data-testid="{entity}-table"> <thead> <tr> <th>{Column1}</th> <th>{Column2}</th> <th>{Column3}</th> <th>Actions</th> </tr> </thead> <tbody> <tr data-testid="{entity}-row"> <td>{Value1}</td> <td>{Value2}</td> <td>{Value3}</td> <td> <div class="btn-group" role="group"> <button class="btn btn-sm btn-outline-primary" data-testid="view-{entity}-button"> <i class="fa-solid fa-eye"></i> </button> <button class="btn btn-sm btn-outline-secondary" data-testid="edit-{entity}-button"> <i class="fa-solid fa-edit"></i> </button> <button class="btn btn-sm btn-outline-danger" data-testid="delete-{entity}-button"> <i class="fa-solid fa-trash"></i> </button> </div> </td> </tr> </tbody> </table> </div> ``` --- ## Behavior & Interactions ### Toast Notifications Success: ```html <div class="toast align-items-center text-bg-success border-0" role="alert" data-testid="success-toast"> <div class="d-flex"> <div class="toast-body"> <i class="fa-solid fa-check-circle me-2"></i> {SuccessMessage} </div> <button type="button" class="btn-close btn-close-white me-2 m-auto" data-bs-dismiss="toast"></button> </div> </div> ``` Error: ```html <div class="toast align-items-center text-bg-danger border-0" role="alert" data-testid="error-toast"> <div class="d-flex"> <div class="toast-body"> <i class="fa-solid fa-exclamation-circle me-2"></i> {ErrorMessage} </div> <button type="button" class="btn-close btn-close-white me-2 m-auto" data-bs-dismiss="toast"></button> </div> </div> ``` ### Modal Dialogs ```html <div class="modal fade" id="{modalId}" tabindex="-1" data-testid="{entity}-modal"> <div class="modal-dialog"> <div class="modal-content"> <div class="modal-header"> <h5 class="modal-title">{ModalTitle}</h5> <button type="button" class="btn-close" data-bs-dismiss="modal"></button> </div> <div class="modal-body"> {ModalContent} </div> <div class="modal-footer"> <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button> <button type="button" class="btn btn-primary" data-testid="{action}-button">{ActionText}</button> </div> </div> </div> </div> ``` --- ## Icon System Font Awesome Pro is used for all icons. Common Icons: - Create: `fa-plus` - Edit: `fa-edit` or `fa-pen` - Delete: `fa-trash` - View: `fa-eye` - Save: `fa-save` or `fa-floppy-disk` - Cancel: `fa-times` or `fa-xmark` - Search: `fa-search` or `fa-magnifying-glass` - Filter: `fa-filter` - Sort: `fa-sort` - Download: `fa-download` - Upload: `fa-upload` --- ## Placeholder Reference - `{ProjectName}` - Name of the project - `{PrimaryColor}` - Primary brand color (hex) - `{SecondaryColor}` - Secondary brand color (hex) - `{EntityName}` - Entity name (capitalized) - `{entity}` - Entity name (lowercase) - `{NavigationItem}` - Navigation menu item - `{ComponentName}` - Component name - `{TooltipText}` - Tooltip message - `{FieldLabel}` - Form field label - `{PlaceholderText}` - Input placeholder text - `{ErrorMessage}` - Validation error message
Step Library Catalog	Document	Build Step Library Test Automation Framework	Required	4	Read the 'Step Library Catalog' artifact from playbook 'Junior Edda'. Type: Document. Required: true. {"type": "Document", "is_required": true, "description": "Index of all available BDD step definitions organized by domain (navigation, forms, tables, auth, assertions, dialogs). Each entry lists: step pattern (Gherkin syntax), what it does, required preconditions, and example usage. This is the shared vocabulary between ESM (writes .features) and TAF (implements steps). ESM must consult this catalog before writing new steps. Produced by TAF-03, updated by TAF-07, consumed by ESM-05 and BPE-04."}
CI Pipeline (GitHub Actions)	Document	Build CI Pipeline Design & Deploy CICD	Optional	2	Read the 'CI Pipeline (GitHub Actions)' artifact from playbook 'Junior Edda'. Type: Document. Required: false. # CI Pipeline (GitHub Actions) Artifact ID: 12 Type: Code Required: True ## Description # ============================================================================== # Artifact: CI Pipeline — GitHub Actions # Workflow: DCD — Design & Deploy CICD # # Thin wrapper around `make` targets. No business logic in YAML. # Copy to {project}/.github/workflows/ci.yml # ============================================================================== name: CI on: push: branches: [main] pull_request: branches: [main] permissions: id-token: write contents: read env: PYTHON_VERSION: '3.12' NODE_VERSION: '20' jobs: # -------------------------------------------------------------------------- # Test — runs on every push and PR # -------------------------------------------------------------------------- test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} cache: 'pip' - name: Install dependencies run: make provision - name: Lint run: make lint - name: Unit tests run: make test - name: Integration tests run: make test-integration # -------------------------------------------------------------------------- # Build — only on main after tests pass (not on PRs) # -------------------------------------------------------------------------- build: needs: test if: github.ref == 'refs/heads/main' && github.event_name == 'push' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Configure AWS credentials (OIDC) uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_ROLE_ARN }} aws-region: ${{ vars.AWS_REGION }} - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} - name: Build and push containers run: make containers - name: Output image tag run: echo "Image tag: $(git rev-parse --short HEAD)" # ============================================================================== # Optional: Agent eval workflow (separate file — do NOT merge into ci.yml) # ============================================================================== # # Default ci.yml above is UNCHANGED. Agent-less projects and baseline PR flow # keep unit + integration (+ AT when added) as the only merge gate. # # When SAO §17 applies: # - Lane 1 (optional PR): append conditional step to ci.yml — see below # - Lanes 3–4: copy to {project}/.github/workflows/agent-eval.yml # # --- Optional PR extension (agents only) — append to ci.yml test job --- # # - name: Agent control-plane proofs (lane 1) # if: vars.AGENTS_ENABLED == 'true' # env: # AGENTS_ENABLED: true # run: make test-agent-proof # # Do not add `-m agent_proof` unconditionally — empty collection fails CI. # Enable the step only after at least one PRF test exists. # ============================================================================== # agent-eval.yml — documented example (workflow_dispatch + schedule) # Copy to {project}/.github/workflows/agent-eval.yml # ============================================================================== ```yaml name: Agent Eval on: workflow_dispatch: schedule: - cron: '0 6 * * ' # nightly lane 3 contract eval permissions: contents: read env: PYTHON_VERSION: '3.12' jobs: live-contract: if: vars.AGENT_EVAL_ENABLED == 'true' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} cache: 'pip' - name: Install dependencies run: make provision - name: Lane 3 — live contract eval (temp=0) env: AGENTS_ENABLED: true LIVE_LLM_API_KEY: ${{ secrets.LIVE_LLM_API_KEY }} run: make test-agent-eval task-quality: if: vars.AGENT_EVAL_ENABLED == 'true' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} cache: 'pip' - name: Install dependencies run: make provision - name: Lane 4 — TASK golden quality band env: AGENTS_ENABLED: true LIVE_LLM_API_KEY: ${{ secrets.LIVE_LLM_API_KEY }} run: make test-agent-quality ``` Gate summary:* \| Workflow \| Lane \| Blocks PR merge? \| \|----------\|------\|------------------\| \| `ci.yml` (default) \| unit + integration (+ AT) \| Yes — unchanged \| \| `ci.yml` optional step \| 1 `@agent_proof` \| Yes — only when `AGENTS_ENABLED` \| \| `agent-eval.yml` \| 3 `@live_llm`, 4 `@quality` \| No — nightly / manual / promotion \|
Fixture Library Catalog	Document	Build Fixture Library Test Automation Framework	Required	4	Read the 'Fixture Library Catalog' artifact from playbook 'Junior Edda'. Type: Document. Required: true. {"type": "Document", "is_required": true, "description": "Index of all available test fixtures and presets. Lists JSON fixtures (session-level seeds), FactoryBoy factories (test-level dynamic data), suite-level presets (team, project, empty), and AutoFixture helpers. Each entry includes: name, scope, what data it provides, dependencies, and example usage. Produced by TAF-04, updated by TAF-07, consumed by ESM-05, BPE-04, BPE-05."}
Screen Flow / Dialogue Map	Diagram	Create Dialogue Maps Envision the System	Required	9	Read the 'Screen Flow / Dialogue Map' artifact from playbook 'Junior Edda'. Type: Diagram. Required: true. OUTPUT: docs/ux/2_dialogue-maps/screen-flow.drawio (also referenced as docs/architecture/screen-flow.drawio in EST activities) FORMAT: Draw.io diagram with domain model and MVP flow swimlanes TEMPLATE: See .windsurf/workflows/FeatureFactory/ESM/artifacts/dialogue_map_template.drawio - Tab 1: Domain Model (entities, relationships, cardinality) - Tab 2: MVP Flow (swimlanes by persona/system, screen boxes with Screen IDs) - Each screen labeled with pattern: {PROJECT}-{ENTITY}-{OPERATION}-{VERSION} - Arrows show navigation flow between screens - Color coding: Entry screens (green), CRUD operations (blue), Delete (red)
Screen Flow / Dialogue Map Template	Template	Create Dialogue Maps Envision the System	Optional	0	Read the 'Screen Flow / Dialogue Map Template' artifact from playbook 'Junior Edda'. Type: Template. Required: false. Draw.io template for creating screen flow diagrams. Includes swimlane structure for acts, screen box conventions (bold border for LIST+FIND entry points), navigation arrow styles, and color coding (blue=FOB, green=Homebase, purple=MCP). Use as starting point for Create Dialogue Maps activity.
Bug Report	Document	Acceptance, Bug Reports & Deploy Fixes Manage Iteration	Required	1	Read the 'Bug Report' artifact from playbook 'Junior Edda'. Type: Document. Required: true. OUTPUT: GitHub Issue created by `report_bug` MCP tool or Feedback UI (`BugReportService.submit_bug`). Produced when a defect is filed during Check Definition of Done (#101), Finalize Feature (#102), or Acceptance, Bug Reports & Deploy Fixes (#183). ## Issue body structure (authoritative) ```markdown ## Description {free-text bug description — for MIN-06 include title, steps, expected vs actual, severity, log excerpts} ## Reproduction - Source: `ui` \| `mcp` - Page URL: `{url when from UI}` ### Page / assistant context (MCP) {page_context when from MCP} ### Form / field snapshot (sanitized) {JSON snapshot or "_No form snapshot provided._"} ## Environment - App version: `{MIMIR_GIT_REVISION}` - MIMIR_ENV: `{env}` - Reported at (UTC): `{ISO8601 timestamp}` ## Reporter - Email: `{reporter_email}` ```
CD Pipeline (GitHub Actions)	Document	Build CD Pipeline Design & Deploy CICD	Optional	2	Read the 'CD Pipeline (GitHub Actions)' artifact from playbook 'Junior Edda'. Type: Document. Required: false. # CD Pipeline (GitHub Actions) Artifact ID: 13 Type: Code Required: True ## Description # ============================================================================== # Artifact: CD Pipeline — GitHub Actions # Workflow: DCD — Design & Deploy CICD # # Thin wrapper around `make` targets. No business logic in YAML. # Copy to {project}/.github/workflows/cd.yml # # Flow: deploy to idle → smoke test → manual approval → switch traffic # ============================================================================== name: CD on: workflow_run: workflows: [CI] types: [completed] branches: [main] workflow_dispatch: inputs: image_tag: description: 'Image tag to deploy (default: latest main SHA)' required: false default: '' target_env: description: 'Target environment (auto-detects idle if empty)' required: false default: '' permissions: id-token: write contents: read env: PYTHON_VERSION: '3.12' jobs: # -------------------------------------------------------------------------- # Deploy to idle environment # -------------------------------------------------------------------------- deploy-idle: if: >- github.event_name == 'workflow_dispatch' \|\| github.event.workflow_run.conclusion == 'success' runs-on: ubuntu-latest environment: staging outputs: idle_env: ${{ steps.detect.outputs.idle }} image_tag: ${{ steps.tag.outputs.tag }} steps: - uses: actions/checkout@v4 - name: Configure AWS credentials uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_ROLE_ARN }} aws-region: ${{ vars.AWS_REGION }} - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies run: make provision - name: Configure kubectl run: aws eks update-kubeconfig --name ${{ vars.EKS_CLUSTER }} --region ${{ vars.AWS_REGION }} - name: Determine image tag id: tag run: \| TAG="${{ github.event.inputs.image_tag }}" if [ -z "$TAG" ]; then TAG=$(git rev-parse --short HEAD) fi echo "tag=$TAG" >> $GITHUB_OUTPUT echo "Using image tag: $TAG" - name: Detect idle environment id: detect run: \| TARGET="${{ github.event.inputs.target_env }}" if [ -z "$TARGET" ]; then # Default: deploy to green (idle) — adjust based on your traffic state TARGET="green" fi echo "idle=$TARGET" >> $GITHUB_OUTPUT echo "Deploying to: $TARGET" - name: Deploy to idle env: IMAGE_TAG: ${{ steps.tag.outputs.tag }} run: make deploy ENV=${{ steps.detect.outputs.idle }} # -------------------------------------------------------------------------- # Smoke tests on idle # -------------------------------------------------------------------------- smoke-test: needs: deploy-idle runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Configure AWS credentials uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_ROLE_ARN }} aws-region: ${{ vars.AWS_REGION }} - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies run: make provision - name: Smoke tests on idle run: make smoke-test ENV=idle # -------------------------------------------------------------------------- # Manual approval → switch production traffic # -------------------------------------------------------------------------- switch: needs: smoke-test runs-on: ubuntu-latest environment: production # REQUIRES MANUAL APPROVAL steps: - uses: actions/checkout@v4 - name: Configure AWS credentials uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_ROLE_ARN }} aws-region: ${{ vars.AWS_REGION }} - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies run: make provision - name: Switch traffic to new deployment run: make switch - name: Verify production run: make smoke-test ENV=prod - name: Final status run: make pipeline-status # ============================================================================== # Optional pre-swap job — agent contract cert (lane 3) # ============================================================================== # # Append when SAO §17 applies. Gated on repository variable AGENT_EVAL_ENABLED. # Default cd.yml above is UNCHANGED for agent-less projects. # # Insert after smoke-test job; wire switch job to `needs: [smoke-test, agent-contract-cert]` # only when this job is present. When AGENT_EVAL_ENABLED is unset, agent-contract-cert # is skipped and switch may keep `needs: smoke-test` only. ```yaml agent-contract-cert: needs: smoke-test if: vars.AGENT_EVAL_ENABLED == 'true' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Configure AWS credentials uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_ROLE_ARN }} aws-region: ${{ vars.AWS_REGION }} - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies run: make provision - name: Lane 3 — live contract eval (temp=0, not ScriptedLLM) env: AGENTS_ENABLED: true LIVE_LLM_API_KEY: ${{ secrets.LIVE_LLM_API_KEY }} STAGING_BASE_URL: ${{ vars.STAGING_URL }} run: make test-agent-eval switch: needs: [smoke-test, agent-contract-cert] # When agent cert disabled, use: needs: smoke-test ``` Notes: - Lane 3 asserts contract bounds only — see artifact 56 Part 3.4. - Failure here is a promotion signal, not a default merge blocker. - Lane 4 (`make test-agent-quality`) remains on `agent-eval.yml` / manual promotion — not in CD swap path by default.
CLAUDE.md Template	Template	Generate AI IDE Configuration Deploy Software Process	Required	1	Read the 'CLAUDE.md Template' artifact from playbook 'Junior Edda'. Type: Template. Required: true. # CLAUDE.md — {ProjectName} Codebase Guide ## What Is {ProjectName} {ExecutiveSummary} --- ## Architecture ### Directory Layout ``` {DirectoryLayout} ``` ### Data Model Hierarchy ``` {DataModelHierarchy} ``` ### Key Design Decisions {KeyDesignDecisions} ### Services Pattern {ServicesPattern} --- ## Documentation Map \| What \| Where \| When to Read \| \|------\|-------\|--------------\| \| System architecture \| `docs/architecture/SAO.md` \| Before big changes \| \| User journey / all Acts \| `docs/features/user_journey.md` \| Feature planning \| \| Feature specs (BDD) \| `docs/features/act-/` \| Before implementing any feature \| \| UI patterns & IA \| `docs/ux/IA_guidelines.md` \| Before building UI \| \| Development rules \| `.windsurf/rules/.md` \| Always active \| \| Process workflows \| `.windsurf/workflows//` \| When running a workflow \| --- ## Available Workflows \| Workflow \| Purpose \| Activities \| When to Use \| \|----------\|---------\|------------\|-------------\| {WorkflowTable} --- ## Available Skills {SkillsTable} --- ## Artifact Templates \| Template \| Workflow \| Purpose \| Location \| \|----------\|----------\|---------\|----------\| {ArtifactTemplateTable} --- ## AI/Human Collaboration ### AI Agent Responsibilities - Code generation following established patterns - Test implementation (unit, integration, e2e) - Documentation generation (docstrings, README updates) - Refactoring within architectural boundaries - Routine CRUD implementations ### Human Developer Responsibilities - Architectural decisions and boundary setting - Code review and quality validation - Security-sensitive implementations - Production deployment decisions ### Quality Gates for AI-Generated Code 1. All tests pass (unit, integration, linting) 2. Code coverage meets project threshold 3. Documentation generated for public APIs 4. Code follows established patterns from SAO.md 5. Human review and approval before merge ### Escalation Rules - Ambiguous requirements → ask human - Architectural decisions outside established patterns → ask human - Security-sensitive code → flag for human review - Complex business logic with edge cases → discuss before implementing --- ## Coding Conventions ### Commit Format (Angular Convention — strict) ``` <type>(<scope>): <subject> <body — what changed and why> <footer> ``` Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` ### Code Style {CodeStyleRules} ### Logging {LoggingConventions} --- ## Development Workflow (How to Build Features) ### Before Implementing Any Feature 1. Read the relevant feature spec in `docs/features/act-/` 2. Read `docs/architecture/SAO.md` for architectural context ### Implementation Order 1. Backend: models → services → views (thin controllers) 2. Frontend: templates + interactions 3. Tests: write before implementation, 100% pass rate required 4. Check Definition of Done → PR {AdditionalBPEDetails} --- ## Testing ```bash {TestCommands} ``` Key rules: - Test-first: write test before implementation - No mocks in integration tests: use real objects/DB - Run tests after every change - Only 100% pass rate counts as success --- ## Running Locally ```bash {SetupCommands} ``` --- ## Placeholder Reference - `{ProjectName}` — Name of the project - `{ExecutiveSummary}` — From SAO.md Executive Summary - `{DirectoryLayout}` — From SAO.md Project Structure section - `{DataModelHierarchy}` — From SAO.md or models - `{KeyDesignDecisions}` — Top 3-5 decisions from SAO.md Design Principles - `{ServicesPattern}` — How services are structured (from SAO.md) - `{WorkflowTable}` — Auto-generated from `.windsurf/workflows//` - `{SkillsTable}` — Auto-generated from `.windsurf/workflows//skills/` - `{ArtifactTemplateTable}` — Auto-generated from `.windsurf/workflows/*/artifacts/` - `{CodeStyleRules}` — From `.windsurf/rules/` or team conventions - `{LoggingConventions}` — From logging rules - `{AdditionalBPEDetails}` — Condensed BPE workflow steps - `{TestCommands}` — pytest commands for the project - `{SetupCommands}` — venv, install, migrate, runserver commands
Copilot Instructions Template	Template	Generate AI IDE Configuration Deploy Software Process	Optional	1	Read the 'Copilot Instructions Template' artifact from playbook 'Junior Edda'. Type: Template. Required: false. # GitHub Copilot Instructions — {ProjectName} ## Project Overview {ExecutiveSummary} ## Architecture ### Tech Stack {TechStack} ### Directory Layout ``` {DirectoryLayout} ``` ### Data Model ``` {DataModelHierarchy} ``` ### Key Design Decisions {KeyDesignDecisions} ## Documentation Map \| What \| Where \| When to Read \| \|------\|-------\|--------------\| \| System architecture \| `docs/architecture/SAO.md` \| Before big changes \| \| User journey / all Acts \| `docs/features/user_journey.md` \| Feature planning \| \| Feature specs (BDD) \| `docs/features/act-/` \| Before implementing any feature \| \| UI patterns & IA \| `docs/ux/IA_guidelines.md` \| Before building UI \| \| Development rules \| `.windsurf/rules/.md` \| Always active \| \| Process workflows \| `.windsurf/workflows//` \| When running a workflow \| ## Available Workflows \| Workflow \| Purpose \| Activities \| When to Use \| \|----------\|---------\|------------\|-------------\| {WorkflowTable} ## Available Skills {SkillsTable} ## Artifact Templates \| Template \| Workflow \| Purpose \| Location \| \|----------\|----------\|---------\|----------\| {ArtifactTemplateTable} ## Coding Conventions ### Commit Format (Angular Convention) ``` <type>(<scope>): <subject> ``` Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` ### Code Style {CodeStyleRules} ### Logging {LoggingConventions} ### Testing - Test runner: {TestRunner} - Test-first: write test before implementation - No mocks in integration tests - 100% pass rate required - Commands: ```bash {TestCommands} ``` ## AI/Human Collaboration ### What AI Should Do - Code generation following established patterns from SAO.md - Test implementation (unit, integration, e2e) - Documentation generation (docstrings, README updates) - Refactoring within architectural boundaries ### What AI Should NOT Do Without Human Approval - Architectural decisions outside established patterns - Security-sensitive implementations - Production deployment decisions - Deleting functions, classes, or files ### Quality Gates 1. All tests pass (unit, integration, linting) 2. Code coverage meets project threshold 3. Documentation generated for public APIs 4. Code follows patterns from SAO.md 5. Human review before merge ### Escalation - Ambiguous requirements → ask human - Outside architectural patterns → ask human - Security-sensitive code → flag for review ## Development Workflow ### Implementation Order 1. Read feature spec in `docs/features/act-/` 2. Read `docs/architecture/SAO.md` for context 3. Backend: models → services → views 4. Frontend: templates + interactions 5. Tests: write before implementation 6. PR with all changes {AdditionalBPEDetails} ## Running Locally ```bash {SetupCommands} ``` ## Placeholder Reference - `{ProjectName}` — Name of the project - `{ExecutiveSummary}` — From SAO.md Executive Summary - `{TechStack}` — Languages, frameworks, databases from SAO.md - `{DirectoryLayout}` — From SAO.md Project Structure section - `{DataModelHierarchy}` — From SAO.md or models - `{KeyDesignDecisions}` — Top 3-5 decisions from SAO.md - `{WorkflowTable}` — Auto-generated from `.windsurf/workflows//` - `{SkillsTable}` — Auto-generated from `.windsurf/workflows//skills/` - `{ArtifactTemplateTable}` — Auto-generated from `.windsurf/workflows/*/artifacts/` - `{CodeStyleRules}` — From `.windsurf/rules/` or team conventions - `{LoggingConventions}` — From logging rules - `{TestRunner}` — pytest, jest, etc. - `{TestCommands}` — Test execution commands - `{AdditionalBPEDetails}` — Condensed BPE workflow steps - `{SetupCommands}` — Setup, install, run commands
Definition of Done Checklist Template	Document	Generate AI IDE Configuration Deploy Software Process	Optional	2	Read the 'Definition of Done Checklist Template' artifact from playbook 'Junior Edda'. Type: Document. Required: false. # Definition of Done Checklist Template Artifact ID: 43 Type: Template Required: True ## Description Reusable checklist template defining 'done' criteria for feature delivery: test coverage, logging, code quality, accessibility, documentation, deployment readiness, and (when SAO §17 applies) agent proof + TASK promotion gates. Created once during DSP process setup and consumed by all BPE iterations. --- # {FeatureName} — Definition of Done Feature: {FeatureScreenID} {FeatureTitle} GitHub Issue: #{IssueNumber} Implementation Plan: `{PlanPath}` --- ## Core Development Rules Checklist ### Test-First Development - [ ] Every function/method has corresponding test(s) - [ ] Feature files in `docs/features/` exist and comply with scenarios - [ ] Tests use pytest framework - [ ] Mocking is minimal (CAP-004 ScriptedLLM carve-out in `@agent_proof` tests only) ### Continuous Testing - [ ] All tests are runnable via `pytest tests/` - [ ] Tests are pytest compatible with proper fixtures - [ ] `tests.log` file exists and contains test output ### Concise Methods - [ ] Top-level (public) methods are 20-30 lines maximum - [ ] Supporting logic is in well-named private methods - [ ] Helper methods have single, focused responsibilities - [ ] Method names are descriptive and clear --- ## Code Quality Rules Checklist ### Import Management - [ ] All imports are at module level - [ ] No imports inside functions/methods - [ ] Dependencies are properly declared ### Log Story Verification - [ ] Implementation plan / issue contains a Log Story Script (Where / Beat / Trigger / Must include) - [ ] Every script row is proven by a passing `_log_story_` caplog test (or `checkpoint.log_story_command` from the iteration manifest) - [ ] Happy and reject paths covered when the scenario has both - [ ] Log levels are appropriate (DEBUG, INFO, WARNING, ERROR) - [ ] No secrets/tokens/passwords appear at INFO in asserted lines - [ ] No deferred logging slice remains in the plan Grep of `logs/app.log` is an audit aid, not the DoD gate. Caplog (or `log_story_command`) is the gate. ### Agent Proof Verification (when SAO §17 / plan Section G in scope) - [ ] Implementation plan / issue contains an Agent Proof Table (PRF ID, workflow, script path, trace beats) - [ ] Every PRF row is proven by a passing `_agent_story_` test marked `@pytest.mark.agent_proof` (or `checkpoint.agent_proof_command` from the iteration manifest) - [ ] Happy and reject paths covered when the PRF is adverse or has a reject sketch - [ ] Tests use CAP-004 ScriptedLLM only — no `FakeLLM`, no `@patch` on ToolExecutor or domain services in `@agent_proof` tests - [ ] LLM scripts exist under `tests/fixtures/llm_scripts/<prf-id>/` for every asserted path - [ ] Trace asserts control-plane beats per artifact 56 Part 4.5 addendum: workflow, tools, domain, board/plan — not assistant wording - [ ] No secrets/tokens/passwords in trace or asserted log lines - [ ] No deferred agent-proof slice remains in the plan Grep of run logs is an audit aid, not the DoD gate. `assert_agent_story` (or `agent_proof_command`) is the gate. ### TASK Promotion Checklist (lane 4 — when SAO §17 TASK-* rows selected; not story merge DoD) - [ ] Golden task fixtures exist under `tests/fixtures/agent_tasks/<task-id>/` with `manifest.yaml` fields: `task_id`, `sc_xx`, `fixture_ref`, `oracle_type`, `pass_band`, `expected_ref` - [ ] `n_runs` and certified pass band recorded in SAO §17 when task is promotion-gated - [ ] Tests marked `@pytest.mark.quality` (+ `@live_llm` when using live provider); temp=0 on eval runs - [ ] Structured oracle is source of truth — Deepeval overlay (if used) is secondary for SC-01 fuzzy tasks only - [ ] `make test-agent-quality` green vs last certified band before human promotion decision - [ ] Lane 4 failure does not block story merge when PRF lane 1 proofs are green — confirm TASK eval remains on nightly / promotion path only --- ## Testing and Quality Assurance Checklist ### Integration Test Standards - [ ] Integration tests in `tests/integration/` exist - [ ] Integration tests avoid mocking (except CAP-004 ScriptedLLM in `@agent_proof` tests) - [ ] Real dependencies are used in integration scenarios ### Commit Conventions - [ ] Recent commit messages follow Angular conventional format - [ ] Commits are atomic and focused - [ ] Breaking changes are documented in commit messages --- ## UI and Frontend Rules Checklist ### Django Views + HTMX - [ ] No DRF views exist for new web UI features - [ ] Django views return HTML templates - [ ] HTMX attributes used for dynamic interactions - [ ] Services layer is shared between MCP and Web UI ### Semantic Naming - [ ] All interactive elements have `data-testid` attributes - [ ] Naming follows kebab-case convention - [ ] Form inputs have proper name and id attributes --- ## Documentation Checklist ### Scenario Writing - [ ] BDD scenarios exist for features - [ ] Feature files are well-structured - [ ] Scenarios cover edge cases and error conditions - [ ] Review GUI — do scenarios match behavior, fields, URLs, design rules? ### TODO Management - [ ] TODO comments exist for incomplete implementations - [ ] TODO items have clear descriptions - [ ] TODOs in dependencies can be ignored --- ## Final Validation Checklist ### Overall Quality Check - [ ] Feature meets acceptance criteria - [ ] Code is production-ready - [ ] Documentation exists and is accurate ### Integration Validation - [ ] Feature integrates with existing system - [ ] No breaking changes introduced - [ ] Dependencies properly declared in requirements.txt ### Deployment Readiness - [ ] Database migrations exist if needed - [ ] Environment variables are documented - [ ] Configuration changes are documented ### Cleanup - [ ] Remove temporary files like debug_.py - [ ] Scan file structure for stray misplaced files - [ ] Remove .log files from repository --- ## Rules Reference Before validating DoD, read each Rule below in this playbook (by slug), then apply it: Required: - `do-test-first` - `do-continuous-testing` - `do-write-concise-methods` - `do-import-on-module-level` - `do-informative-logging` - `do-assert-log-story` - `do-assert-agent-story` (when SAO §17 / Section G in scope) - `do-not-mock-in-integration-tests` - `do-follow-commit-convention` - `do-semantic-versioning-on-ui-elements` - `pytest` Activity-specific: - Observability DoD is Log Story Verification (caplog / `log_story_command`), not "logging statements exist". - Agent DoD is Agent Proof Verification (`agent_proof_command` / `@agent_proof`), not "the agent loop exists" or Behave AT alone. - TASK-* lane 4 is Promotion Checklist only — artifact 56 Part 4.6; skill Agent Task Eval. --- ## Sign-off - [ ] All applicable checklist items verified - [ ] Deviations documented and approved (or deferred as GitHub issues with `deferred` label) - [ ] Ready for PR / merge Reviewer: {ReviewerName} Date: {SignOffDate} --- ## Placeholder Reference - `{FeatureName}` — Feature name - `{FeatureScreenID}` — Screen ID (e.g., FOB-AUTH-LOGIN-1) - `{IssueNumber}` — GitHub issue number - `{PlanPath}` — Path to implementation plan - `{ReviewerName}` — Human reviewer - `{SignOffDate}` — ISO date
Feature Files	Document	Write Feature Files Envision the System	Required	9	Read the 'Feature Files' artifact from playbook 'Junior Edda'. Type: Document. Required: true. OUTPUT: docs/features/act-X-{entity}/{entity}-{operation}.feature TEMPLATE: Feature: {ScreenID} {EntityName} {Operation} As a {PersonaRole} ({PersonaName}) I want to {UserGoal} So that {BusinessValue} Background: Given {PersonaName} is authenticated in {SystemName} And {InitialContext} Scenario: {ScenarioID} {ScenarioTitle} - Happy Path Given {PersonaName} is on the {ScreenName} page When {PersonaName} clicks the [{ButtonName}] button Then {PersonaName} is redirected to {TargetScreenID} Scenario: {ScenarioID} Search Functionality Given {PersonaName} is on the {ScreenName} page When {PersonaName} enters "{SearchTerm}" in the search box Then {PersonaName} sees only {EntityName} matching "{SearchTerm}" Scenario: {ScenarioID} Form Validation Error Given {PersonaName} is on the {CreateScreenID} page When {PersonaName} leaves "{RequiredField}" empty And {PersonaName} clicks [Save] Then {PersonaName} sees error message "{ErrorMessage}" See .windsurf/workflows/FeatureFactory/ESM/artifacts/feature_file_template.feature for complete template with all scenario types
Feature File Template (Gherkin)	Template	Write Feature Files Envision the System	Required	2	Read the 'Feature File Template (Gherkin)' artifact from playbook 'Junior Edda'. Type: Template. Required: true. Feature: {ScreenID} {EntityName} {Operation} As a {PersonaRole} ({PersonaName}) I want to {UserGoal} So that {BusinessValue} Background: Given {PersonaName} is authenticated in {SystemName} And {InitialContext} Scenario: {ScenarioID} {ScenarioTitle} Given {GivenContext} \| {Column1} \| {Column2} \| {Column3} \| {Column4} \| \| {Value1} \| {Value2} \| {Value3} \| {Value4} \| \| {Value5} \| {Value6} \| {Value7} \| {Value8} \| When {WhenAction} Then {ThenOutcome} And {AdditionalOutcome} Scenario: {ScenarioID} {ScenarioTitle} - Happy Path Given {PersonaName} is on the {ScreenName} page And {Precondition} When {PersonaName} clicks the [{ButtonName}] button Then {PersonaName} is redirected to {TargetScreenID} And {PersonaName} sees {ExpectedResult} Scenario: {ScenarioID} {ScenarioTitle} - Search Functionality Given {PersonaName} is on the {ScreenName} page And {PersonaName} has {EntityName} including "{ExampleName}" When {PersonaName} enters "{SearchTerm}" in the search box Then {PersonaName} sees only {EntityName} matching "{SearchTerm}" in {SearchFields} And "{ExampleName}" appears in the results And unmatched {EntityName} are hidden Scenario: {ScenarioID} {ScenarioTitle} - Search with No Results Given {PersonaName} is on the {ScreenName} page When {PersonaName} enters "{NonExistentTerm}" in the search box Then {PersonaName} sees "No {EntityName} found matching '{NonExistentTerm}'" And {PersonaName} sees a [Clear Search] button And the {EntityName} table is empty Scenario: {ScenarioID} {ScenarioTitle} - Filter by Status Given {PersonaName} is on the {ScreenName} page And {PersonaName} has both {Status1} and {Status2} {EntityName} When {PersonaName} selects "{Status1}" from the Status filter Then {PersonaName} sees only {Status1} {EntityName} And {Status2} {EntityName} are hidden And the filter badge shows "Status: {Status1}" Scenario Outline: {ScenarioID} {ScenarioTitle} - Filter by Category Given {PersonaName} is on the {ScreenName} page And {PersonaName} has {EntityName} from different categories When {PersonaName} selects "<category>" from the Category filter Then {PersonaName} sees only "<category>" {EntityName} And the filter badge shows "Category: <category>" Examples: \| category \| \| {Category1} \| \| {Category2} \| \| {Category3} \| Scenario: {ScenarioID} {ScenarioTitle} - Clear All Filters Given {PersonaName} is on the {ScreenName} page And {PersonaName} has applied Status filter "{Status1}" And {PersonaName} has applied Category filter "{Category1}" When {PersonaName} clicks [Clear Filters] Then all filters are removed And {PersonaName} sees all {EntityName} regardless of status or category And no filter badges are displayed Scenario: {ScenarioID} {ScenarioTitle} - Sort by Column Given {PersonaName} is on the {ScreenName} page And {PersonaName} has multiple {EntityName} When {PersonaName} clicks the "{ColumnName}" column header Then {EntityName} are sorted by {ColumnName} (ascending) When {PersonaName} clicks the "{ColumnName}" column header again Then {EntityName} are sorted by {ColumnName} (descending) And a sort indicator appears on the "{ColumnName}" column Scenario: {ScenarioID} {ScenarioTitle} - Navigate to View Details Given {PersonaName} is on the {ScreenName} page And "{ExampleName}" is in the list When {PersonaName} clicks [View] in the Actions menu for "{ExampleName}" Then {PersonaName} is redirected to {ViewScreenID} And {PersonaName} sees the detail page for "{ExampleName}" Scenario: {ScenarioID} {ScenarioTitle} - Navigate to Edit Given {PersonaName} is on the {ScreenName} page And "{ExampleName}" is in the list And {PersonaName} is the author of "{ExampleName}" When {PersonaName} clicks [Edit] in the Actions menu for "{ExampleName}" Then {PersonaName} is redirected to {EditScreenID} And {PersonaName} sees the edit form pre-populated with {EntityName} data Scenario: {ScenarioID} {ScenarioTitle} - Open Delete Confirmation Given {PersonaName} is on the {ScreenName} page And "{ExampleName}" is in the list When {PersonaName} clicks [Delete] in the Actions menu for "{ExampleName}" Then the {DeleteScreenID} modal appears And the modal shows "Delete {EntityName}?" And the modal shows {EntityName} details for "{ExampleName}" Scenario: {ScenarioID} {ScenarioTitle} - Empty State Display Given {PersonaName} is on the {ScreenName} page And {PersonaName} has zero {EntityName} Then {PersonaName} sees an empty {IllustrationName} illustration And {PersonaName} sees "No {EntityName} yet" And {PersonaName} sees "{EmptyStateMessage}" And {PersonaName} sees action buttons: \| button \| \| {Action1} \| \| {Action2} \| \| {Action3} \| Scenario: {ScenarioID} {ScenarioTitle} - Pagination Given {PersonaName} is on the {ScreenName} page And {PersonaName} has {TotalCount} {EntityName} When the page loads Then {PersonaName} sees the first {PageSize} {EntityName} And {PersonaName} sees pagination controls at the bottom And the controls show "Page 1 of {TotalPages}" When {PersonaName} clicks "Next Page" Then {PersonaName} sees {EntityName} {NextRangeStart}-{NextRangeEnd} And the controls show "Page 2 of {TotalPages}" Scenario: {ScenarioID} {ScenarioTitle} - Combine Search and Filter Given {PersonaName} is on the {ScreenName} page And {PersonaName} has multiple {EntityName} When {PersonaName} enters "{SearchTerm}" in the search box And {PersonaName} selects "{Status1}" from the Status filter Then {PersonaName} sees only {Status1} {EntityName} with "{SearchTerm}" in {SearchFields} And both search term and filter badge are displayed And results match both criteria Scenario: {ScenarioID} {ScenarioTitle} - Form Validation Error Given {PersonaName} is on the {CreateScreenID} page When {PersonaName} leaves "{RequiredField}" empty And {PersonaName} clicks [Save] Then {PersonaName} sees error message "{ErrorMessage}" below "{RequiredField}" And the [Save] button remains disabled And the form is not submitted Scenario: {ScenarioID} {ScenarioTitle} - Create Success Given {PersonaName} is on the {CreateScreenID} page When {PersonaName} fills in: \| field \| value \| \| {Field1} \| {Value1} \| \| {Field2} \| {Value2} \| \| {Field3} \| {Value3} \| And {PersonaName} clicks [Save] Then {PersonaName} sees green toast "{EntityName} '{Value1}' created successfully" And {PersonaName} is redirected to {ViewScreenID} And the new {EntityName} appears in the list Scenario: {ScenarioID} {ScenarioTitle} - Edit Success Given {PersonaName} is on the {EditScreenID} page for "{ExampleName}" And the form is pre-populated with current values When {PersonaName} changes "{Field1}" to "{NewValue}" And {PersonaName} clicks [Save Changes] Then {PersonaName} sees green toast "{EntityName} updated successfully" And {PersonaName} is redirected to {ViewScreenID} And the updated value "{NewValue}" is displayed Scenario: {ScenarioID} {ScenarioTitle} - Delete Success Given {PersonaName} is on the {DeleteScreenID} modal for "{ExampleName}" When {PersonaName} clicks [Delete] Then {PersonaName} sees green toast "{EntityName} deleted successfully" And {PersonaName} is redirected to {ListScreenID} And "{ExampleName}" is removed from the table Scenario: {ScenarioID} {ScenarioTitle} - Delete with Dependencies Warning Given {PersonaName} is on the {DeleteScreenID} modal for "{ExampleName}" And "{ExampleName}" has {DependencyCount} related {DependencyEntity} Then the modal shows warning "This will also delete {DependencyCount} related {DependencyEntity}" When {PersonaName} clicks [Delete] Then both {EntityName} and related {DependencyEntity} are deleted # ============================================================ # PLACEHOLDER REFERENCE # ============================================================ # {ScreenID} - Unique screen identifier (e.g., FOB-PLAYBOOKS-LIST+FIND-1) # {EntityName} - Entity name capitalized (e.g., Playbook, Workflow) # {Operation} - CRUD operation (List and Search, Create, View, Edit, Delete) # {PersonaRole} - User role (e.g., methodology author, developer) # {PersonaName} - User persona name (e.g., Maria, Mike) # {UserGoal} - What the user wants to accomplish # {BusinessValue} - Why this matters to the user # {SystemName} - System name (e.g., FOB, HB) # {ScenarioID} - Unique scenario identifier # {ScenarioTitle} - Descriptive scenario title # {GivenContext} - Initial state/precondition # {WhenAction} - User action # {ThenOutcome} - Expected result # {ScreenName} - Human-readable screen name # {ButtonName} - Button label # {TargetScreenID} - Destination screen ID # {ExpectedResult} - What user should see # {SearchTerm} - Search query # {SearchFields} - Fields to search in # {Status1}, {Status2} - Status values # {Category1}, {Category2}, {Category3} - Category values # {ColumnName} - Table column name # {ViewScreenID}, {EditScreenID}, {DeleteScreenID}, {CreateScreenID}, {ListScreenID} - Screen IDs # {ExampleName} - Example entity name # {IllustrationName} - Empty state illustration name # {EmptyStateMessage} - Empty state message # {Action1}, {Action2}, {Action3} - Action button labels # {TotalCount} - Total number of items # {PageSize} - Items per page # {TotalPages} - Total number of pages # {NextRangeStart}, {NextRangeEnd} - Pagination range # {RequiredField} - Required form field name # {ErrorMessage} - Validation error message # {Field1}, {Field2}, {Field3} - Form field names # {Value1}, {Value2}, {Value3} - Form field values # {NewValue} - Updated value # {DependencyCount} - Number of dependent items # {DependencyEntity} - Type of dependent entity
Windsurf/Cursor Rules Template	Template	Generate AI IDE Configuration Deploy Software Process	Optional	1	Read the 'Windsurf/Cursor Rules Template' artifact from playbook 'Junior Edda'. Type: Template. Required: false. # {ProjectName} — AI Context > When to use: At the start of every new conversation or task. This file provides the AI agent with a complete map of the project's documentation, workflows, skills, and artifact templates. ## Project Overview {ExecutiveSummary} ## Architecture Quick Reference - Tech Stack: {TechStack} - Key Design Decisions: {KeyDesignDecisionsSummary} - Full details: Read `docs/architecture/SAO.md` ## Documentation Map \| What \| Where \| When to Read \| \|------\|-------\|--------------\| \| System architecture \| `docs/architecture/SAO.md` \| Before big changes \| \| User journey / all Acts \| `docs/features/user_journey.md` \| Feature planning \| \| Feature specs (BDD) \| `docs/features/act-/` \| Before implementing any feature \| \| UI patterns & IA \| `docs/ux/IA_guidelines.md` \| Before building UI \| \| Development rules \| `.windsurf/rules/.md` \| Always active (auto-loaded) \| \| Process workflows \| `.windsurf/workflows//` \| When running a workflow \| ## Available Workflows \| Workflow \| Purpose \| Activities \| Location \| \|----------\|---------\|------------\|----------\| {WorkflowTable} Primary feature delivery workflow: BPE (Build Feature) — use this for all feature implementation. ## Available Skills {SkillsTable} ## Artifact Templates \| Template \| Workflow \| Purpose \| Location \| \|----------\|----------\|---------\|----------\| {ArtifactTemplateTable} ## AI/Human Collaboration Summary AI does: Code generation, test implementation, documentation, refactoring within patterns. Human does: Architecture decisions, code review, security-sensitive work, deployment. Escalate to human: Ambiguous requirements, outside-pattern decisions, security code. Quality gates: All tests pass → coverage threshold met → docs generated → human review → merge. ## Development Workflow (BPE Summary) 1. Read feature spec in `docs/features/act-/` 2. Read `docs/architecture/SAO.md` for context 3. Backend: models → services → views 4. Frontend: templates + interactions 5. Tests: write before implementation, 100% pass rate 6. PR with all changes ## Existing Rules (auto-loaded) The following rules in `.windsurf/rules/` are automatically active. Do NOT duplicate their content: {ExistingRulesList} ## Placeholder Reference - `{ProjectName}` — Name of the project - `{ExecutiveSummary}` — From SAO.md Executive Summary - `{TechStack}` — Languages, frameworks, databases - `{KeyDesignDecisionsSummary}` — 1-2 sentence summary of top decisions - `{WorkflowTable}` — Auto-generated from `.windsurf/workflows//` - `{SkillsTable}` — Auto-generated from `.windsurf/workflows//skills/` - `{ArtifactTemplateTable}` — Auto-generated from `.windsurf/workflows//artifacts/` - `{ExistingRulesList}` — Auto-generated list of `.windsurf/rules/.md` files with descriptions
E2E Test Configuration	Code	Establish E2E Infrastructure Test Automation Framework	Required	3	Read the 'E2E Test Configuration' artifact from playbook 'Junior Edda'. Type: Code. Required: true. {"type": "Code", "is_required": true, "description": "E2E test infrastructure configuration: @e2e tag exclusion from default runs, --base-url parameter for environment targeting (local/staging/prod), --db-uri parameter for initial data loading, screenshot capture configuration (after every step), LiveServerTestCase integration for local runs, and multi-phase .feature execution setup. Enables 'certify any environment' pattern. Produced by TAF-06, consumed by BPE-05 and DCD-05."}
HTML Mockups	Code	Create Mockups Envision the System	Required	5
HTML Mockups Template	Template	Create Mockups Envision the System	Optional	0
Infra GH Actions Workflow	Code	Create Infra GH Workflow Design & Deploy Cloud Infra	Required	1	Read the 'Infra GH Actions Workflow' artifact from playbook 'Junior Edda'. Type: Code. Required: true. # ============================================================================== # Artifact: Infrastructure GitHub Actions Workflow # Workflow: DCI — Design & Deploy Cloud Infra # # Thin wrapper around `make` targets. No business logic in YAML. # Copy to {project}-infra/.github/workflows/infra.yml # ============================================================================== name: Infrastructure on: push: branches: [main] paths: - 'stacks/**' - 'app.py' - 'cdk.json' - 'requirements.txt' workflow_dispatch: inputs: action: description: 'Infrastructure action to perform' required: true type: choice options: - deploy - destroy - status - traffic-switch - traffic-rollback - traffic-status permissions: id-token: write # For OIDC federation with AWS contents: read env: PYTHON_VERSION: '3.12' NODE_VERSION: '20' jobs: # -------------------------------------------------------------------------- # Deploy — runs on push to main (stack changes) or manual trigger # -------------------------------------------------------------------------- deploy: if: >- github.event_name == 'push' \|\| (github.event_name == 'workflow_dispatch' && github.event.inputs.action == 'deploy') runs-on: ubuntu-latest environment: infrastructure steps: - uses: actions/checkout@v4 - name: Configure AWS credentials (OIDC) uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_ROLE_ARN }} aws-region: ${{ vars.AWS_REGION }} - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} - name: Setup Node (for CDK CLI) uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} - name: Install dependencies run: make provision - name: Synthesize (dry run) run: make synth - name: Deploy all stacks run: make deploy - name: Show status run: make status # -------------------------------------------------------------------------- # Destroy — manual trigger only, requires infrastructure environment approval # -------------------------------------------------------------------------- destroy: if: >- github.event_name == 'workflow_dispatch' && github.event.inputs.action == 'destroy' runs-on: ubuntu-latest environment: infrastructure # Add required reviewers for safety steps: - uses: actions/checkout@v4 - name: Configure AWS credentials (OIDC) uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_ROLE_ARN }} aws-region: ${{ vars.AWS_REGION }} - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} - name: Setup Node uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} - name: Install dependencies run: make provision - name: Destroy all stacks run: make destroy # -------------------------------------------------------------------------- # Traffic switch — requires production environment approval # -------------------------------------------------------------------------- traffic-switch: if: >- github.event_name == 'workflow_dispatch' && github.event.inputs.action == 'traffic-switch' runs-on: ubuntu-latest environment: production # Manual approval required steps: - uses: actions/checkout@v4 - name: Configure AWS credentials (OIDC) uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_ROLE_ARN }} aws-region: ${{ vars.AWS_REGION }} - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies run: make provision - name: Show current state run: make traffic-status - name: Switch traffic run: make traffic-switch - name: Verify switch run: make traffic-status # -------------------------------------------------------------------------- # Traffic rollback — requires production environment approval # -------------------------------------------------------------------------- traffic-rollback: if: >- github.event_name == 'workflow_dispatch' && github.event.inputs.action == 'traffic-rollback' runs-on: ubuntu-latest environment: production steps: - uses: actions/checkout@v4 - name: Configure AWS credentials (OIDC) uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_ROLE_ARN }} aws-region: ${{ vars.AWS_REGION }} - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies run: make provision - name: Rollback traffic run: make traffic-rollback - name: Verify rollback run: make traffic-status # -------------------------------------------------------------------------- # Status — no approvals needed # -------------------------------------------------------------------------- status: if: >- github.event_name == 'workflow_dispatch' && (github.event.inputs.action == 'status' \|\| github.event.inputs.action == 'traffic-status') runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Configure AWS credentials (OIDC) uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_ROLE_ARN }} aws-region: ${{ vars.AWS_REGION }} - name: Setup Python uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_VERSION }} - name: Setup Node uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} - name: Install dependencies run: make provision - name: Infrastructure status run: make status - name: Traffic status run: make traffic-status
Makefile Template	Document	Create Makefile Bootstrap Project	Optional	9	Read the 'Makefile Template' artifact from playbook 'Junior Edda'. Type: Document. Required: false. # Makefile Template Artifact ID: 11 Type: Code Required: True ## Description # ============================================================================== # Makefile Template — FeatureFactory # ============================================================================== # # Single entry point for all dev, infra, and deployment operations. # CI/CD pipelines call these targets — no business logic in GH Actions. # # Sections: # General — help # Provision — prerequisites, venv, deps, db # Development — run, shell, dbshell # Testing — test, test-unit, test-integration, test-e2e, coverage # Code Quality — lint, format, typecheck, precommit # Database — migrate, makemigrations # Infrastructure — infra-deploy, infra-destroy, infra-status, traffic-switch, traffic-rollback (DCI) # Deployment — containers, deploy, smoke-test, switch, rollback, verify (DCD) # Cleanup — clean, clean-all # # Usage: # make help — show all targets # make provision — install everything from scratch # make run — start dev server # make test — run all tests # # Extension points: # DCI workflow adds ##@ Infrastructure targets # DCD workflow adds ##@ Deployment targets # ============================================================================== .PHONY: help provision run test test-unit test-integration test-e2e test-agent-proof test-agent-eval test-agent-quality lint format clean # Default target .DEFAULT_GOAL := help # ------------------------------------------------------------------------------ # Variables — adapt to your stack (read from SAO.md Technology Stack Table) # ------------------------------------------------------------------------------ VENV := .venv PYTHON := $(VENV)/bin/python PIP := $(VENV)/bin/pip PYTEST := $(VENV)/bin/pytest MANAGE := $(PYTHON) manage.py PORT := 8000 # Infrastructure variables (set by DCI workflow) # AWS_REGION := us-east-1 # CDK_DIR := ../$(PROJECT)-infra # EKS_CLUSTER := $(PROJECT)-cluster # Deployment variables (set by DCD workflow) # ECR_REPO := $(AWS_ACCOUNT).dkr.ecr.$(AWS_REGION).amazonaws.com/$(PROJECT) # HELM_CHART := deploy/helm/$(PROJECT) # ENV := local # NAMESPACE := $(ENV) # ============================================================================== ##@ General # ============================================================================== help: ## Show this help message @awk 'BEGIN {FS = ":.##"; printf "\nUsage:\n make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.?##/ { printf " \033[36m%-20s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) }' $(MAKEFILE_LIST) # ============================================================================== ##@ Provision # ============================================================================== provision: _check-prereqs _venv _pip-install _npm-install _db-init ## Install all prerequisites & dependencies @echo "✅ Provisioning complete. Run 'make run' to start." _check-prereqs: @echo "Checking prerequisites..." @command -v python3 >/dev/null 2>&1 \|\| { echo "❌ python3 not found"; exit 1; } @command -v git >/dev/null 2>&1 \|\| { echo "❌ git not found"; exit 1; } @echo "✅ Prerequisites OK" _venv: @if [ ! -d "$(VENV)" ]; then \ echo "Creating virtual environment..."; \ python3 -m venv $(VENV); \ $(PIP) install --upgrade pip; \ else \ echo "✅ Virtual environment exists"; \ fi _pip-install: @echo "Installing Python dependencies..." @$(PIP) install -r requirements.txt -q _npm-install: @if [ -f "package.json" ]; then \ echo "Installing Node.js dependencies..."; \ npm install; \ fi _db-init: @echo "Running database migrations..." @$(MANAGE) migrate --run-syncdb # ============================================================================== ##@ Development # ============================================================================== run: ## Start development server @$(MANAGE) runserver 0.0.0.0:$(PORT) shell: ## Open Django shell @$(MANAGE) shell dbshell: ## Open database shell @$(MANAGE) dbshell # ============================================================================== ##@ Testing # ============================================================================== test: ## Run all tests @$(PYTEST) tests/ -v --tb=short 2>&1 \| tee tests.log test-unit: ## Run unit tests only @$(PYTEST) tests/unit/ -v --tb=short test-integration: ## Run integration tests only @$(PYTEST) tests/integration/ -v --tb=short test-e2e: ## Run E2E tests only @$(PYTEST) tests/e2e/ -v --tb=short test-watch: ## Run tests in watch mode (requires pytest-watch) @$(VENV)/bin/ptw tests/ -- -v --tb=short coverage: ## Run tests with coverage report @$(PYTEST) tests/ --cov --cov-report=html --cov-report=term-missing # ============================================================================== ##@ Code Quality # ============================================================================== lint: ## Run linter (ruff check) @$(VENV)/bin/ruff check . format: ## Auto-format code (ruff format) @$(VENV)/bin/ruff format . @$(VENV)/bin/ruff check --fix . typecheck: ## Run type checker (if configured) @$(VENV)/bin/mypy . \|\| echo "mypy not configured — skipping" precommit: ## Run all pre-commit hooks @$(VENV)/bin/pre-commit run --all-files # ============================================================================== ##@ Database # ============================================================================== migrate: ## Run database migrations @$(MANAGE) migrate makemigrations: ## Create new migrations @$(MANAGE) makemigrations # ============================================================================== ##@ Infrastructure (added by DCI workflow) # ============================================================================== # # Uncomment and configure after completing DCI workflow. # These targets operate on the infra repo (CDK stacks). # # infra-deploy: ## Deploy all CDK stacks (VPC, EKS, ECR, Route53) # cd $(CDK_DIR) && cdk deploy --all --require-approval never # # infra-destroy: ## Destroy all CDK stacks (DANGEROUS) # cd $(CDK_DIR) && cdk destroy --all --force # # infra-status: ## Show CDK stack status # cd $(CDK_DIR) && cdk list && aws cloudformation describe-stacks --query 'Stacks[].{Name:StackName,Status:StackStatus}' --output table # # traffic-switch: ## Switch prod/idle DNS (Route53 weighted records) # @echo "Switching traffic: idle → prod..." # $(PYTHON) scripts/traffic_switch.py --action switch --region $(AWS_REGION) # # traffic-rollback: ## Rollback DNS to previous prod # @echo "Rolling back traffic..." # $(PYTHON) scripts/traffic_switch.py --action rollback --region $(AWS_REGION) # ============================================================================== ##@ Deployment (added by DCD workflow) # ============================================================================== # # Uncomment and configure after completing DCD workflow. # These targets handle containerization, Helm deploys, and blue/green switching. # # containers: ## Build and push Docker images to ECR # @echo "Building containers..." # docker build -t $(ECR_REPO):$(shell git rev-parse --short HEAD) . # docker push $(ECR_REPO):$(shell git rev-parse --short HEAD) # # deploy: ## Deploy to environment (ENV=local\|blue\|green) # @echo "Deploying to $(ENV)..." # helm upgrade --install $(PROJECT) $(HELM_CHART) \ # -f $(HELM_CHART)/values-$(ENV).yaml \ # --set image.tag=$(shell git rev-parse --short HEAD) \ # --namespace $(NAMESPACE) --create-namespace # # smoke-test: ## Run smoke tests against environment (ENV=blue\|green) # @echo "Running smoke tests on $(ENV)..." # $(PYTEST) tests/smoke/ -v --base-url=https://$(ENV).$(DOMAIN) # # switch: ## Swap prod ↔ idle (blue/green) # @echo "Switching prod ↔ idle..." # $(PYTHON) scripts/traffic_switch.py --action switch --region $(AWS_REGION) # @echo "✅ Switched. Verify at https://$(DOMAIN)" # # rollback: ## Rollback to previous deployment # @echo "Rolling back deployment..." # $(PYTHON) scripts/traffic_switch.py --action rollback --region $(AWS_REGION) # # verify: ## Run full verification (test + integration + smoke) # $(MAKE) test # $(MAKE) test-integration # $(MAKE) smoke-test ENV=$(ENV) # # pipeline-status: ## Show current pipeline/deployment status # @echo "=== EKS Pods ===" # kubectl get pods -n blue # kubectl get pods -n green # @echo "=== DNS ===" # dig +short prod.$(DOMAIN) # dig +short idle.$(DOMAIN) # ============================================================================== ##@ Agent eval (optional — when SAO §17 applies) # ============================================================================== # # Gated on AGENTS_ENABLED=true. No-op with message when unset — agent-less projects # keep default `make test` as the only merge gate. See artifact 56 Part 3.4 / 4.6 # and TFK-05 for lane mapping. # # Lane 1: test-agent-proof — PRF control-plane (@agent_proof, ScriptedLLM) # Lane 3: test-agent-eval — live contract eval (@live_llm, temp=0) # Lane 4: test-agent-quality — TASK-* golden oracle (@quality) .PHONY: test-agent-proof test-agent-eval test-agent-quality test-agent-proof: ## Lane 1 — PRF control-plane proofs (ScriptedLLM) ifeq ($(AGENTS_ENABLED),true) @$(PYTEST) tests/integration/agent/ -v -m agent_proof --tb=short 2>&1 \| tee -a tests.log else @echo "skip: agents N/A (SAO §17) — set AGENTS_ENABLED=true to run" endif test-agent-eval: ## Lane 3 — live contract eval (temp=0, not ScriptedLLM) ifeq ($(AGENTS_ENABLED),true) @$(PYTEST) tests/ -v -m live_llm --tb=short 2>&1 \| tee -a tests.log else @echo "skip: agents N/A (SAO §17) — set AGENTS_ENABLED=true to run" endif test-agent-quality: ## Lane 4 — TASK-* golden task quality band ifeq ($(AGENTS_ENABLED),true) @$(PYTEST) tests/ -v -m quality --tb=short 2>&1 \| tee -a tests.log else @echo "skip: agents N/A (SAO §17) — set AGENTS_ENABLED=true to run" endif # ============================================================================== ##@ Cleanup # ============================================================================== clean: ## Remove build artifacts, caches, logs @find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null \|\| true @find . -type f -name "*.pyc" -delete 2>/dev/null \|\| true @rm -rf .pytest_cache htmlcov .coverage coverage.xml @rm -rf node_modules @rm -f tests.log @echo "✅ Cleaned" clean-all: clean ## Remove everything including venv @rm -rf $(VENV) @echo "✅ Cleaned all (including venv)"
INFRA Verification Checklist (EB Reference)	Document	Deploy & Verify Cloud Environment Design & Deploy Cloud Infra	Required	0	Read the 'INFRA Verification Checklist (EB Reference)' artifact from playbook 'Junior Edda'. Type: Document. Required: true. # Infrastructure Verification Project: {project} Deployment Style: Elastic Beanstalk Verified: {date} Verified By: {name} ## CDK Stacks \| Stack \| Status \| Notes \| \|-------\|--------\|-------\| \| Network (VPC, SG) \| ☐ \| \| \| App (EB, ECR ref, CI IAM) \| ☐ \| Both envs Ready \| \| Backups (S3, SSM) \| ☐ \| Bucket + lifecycle 90d \| \| SES \| ☐ \| Optional \| \| DNS (Route53 CNAME) \| ☐ \| Points to `{project}-prod.eba-…`, not ALB ARN \| ## Platform Snapshot \| Check \| Status \| Notes \| \|-------\|--------\|-------\| \| `export_eb_live_settings.py` run \| ☐ \| \| \| `diff_eb_live_vs_cdk.py` → 0 diffs \| ☐ \| Secrets excluded \| ## EB Environments \| Env \| Status \| Health \| CNAME \| VersionLabel \| \|-----\|--------\|--------\|-------\|--------------\| \| `{project}-prod` \| ☐ \| ☐ \| ☐ \| ☐ \| \| `{project}-idle` \| ☐ \| ☐ \| ☐ \| ☐ \| ## ECR \| Check \| Status \| Notes \| \|-------\|--------\|-------\| \| Push test image \| ☐ \| \| \| Pull from EB instance role \| ☐ \| \| ## DNS & TLS \| Check \| Status \| Notes \| \|-------\|--------\|-------\| \| `dig app.example.com` → prod EB label \| ☐ \| \| \| HTTPS /health/ on prod domain \| ☐ \| ACM on ALB :443 \| \| HTTP /health/ on idle CNAME \| ☐ \| Used for CI smoke \| ## Backup & SSM \| Check \| Status \| Notes \| \|-------\|--------\|-------\| \| SSM managed instances \| ☐ \| Both EB envs \| \| Manual `make backup` → S3 \| ☐ \| \| \| CI backup in deploy-idle.sh \| ☐ \| Fail-closed \| ## End-to-End Blue/Green \| Step \| Status \| Notes \| \|------\|--------\|-------\| \| `gh release create` → deploy-idle \| ☐ \| \| \| Idle smoke revision match \| ☐ \| \| \| `make swap` → prod smoke \| ☐ \| Wait ≥90s after swap \| \| Rollback (second swap) tested \| ☐ \| Old version still on other env \| ## GitHub Actions \| Workflow \| Status \| Notes \| \|----------\|--------\|-------\| \| build-and-deploy on release \| ☐ \| \| \| promote.yml manual + approval \| ☐ \| \| \| infra.yml on infra/ changes \| ☐ \| Optional \|
Iteration Lessons Learned Document	Document	TL Closes Sprint with Lessons and Release Manage Iteration	Required	0	Read the 'Iteration Lessons Learned Document' artifact from playbook 'Junior Edda'. Type: Document. Required: true. A structured Markdown document recording the retrospective of a completed iteration. Produced by the Team Lead (AI orchestrator) during the sprint close activity that supersedes Activity 182 (Close Iteration) in Workflow 17. Authored using Skill 28 (Lessons Learned Writing). Skill 28 should be linked to the producing close activity. Location: `docs/lessons_learned/ITER-{YYYYMMDD}-{slug}.md` Front-matter fields: iteration slug, milestone number + goal, scenarios_planned, scenarios_delivered, fix_cycles, uat_blockers_found, uat_blockers_resolved, test_debt_found. Sections: - Execution Review (per-scenario deviations and drift signals during Execute, Activity 181) - Acceptance Testing (Saga scope, blocker count, fix cycle count) - Test Debt (stale test assertions filed, coverage gaps identified) - Architecture Notes (SAO.md updates applied or deferred as sao-update issues) Lifecycle: created during close activity, committed to `docs/lessons_learned/`, then read-only. Consumed by: Orient & Validate Scope (Activity 140 in Plan Iteration workflow) as velocity and scope-risk context for the next iteration.
Release Notes Draft	Document	TL Closes Sprint with Lessons and Release Manage Iteration	Required	0	Read the 'Release Notes Draft' artifact from playbook 'Junior Edda'. Type: Document. Required: true. A single artifact with two lifecycle stages, both produced during the sprint close activity that supersedes Activity 182 (Close Iteration) in Workflow 17. Stage 1 — Draft (internal): Assembled by the Team Lead (AI orchestrator) and presented to the human at the release gate. Content: iteration slug + goal, list of delivered scenarios with linked GitHub issues, acceptance verdict (CLEAN) with blocker resolution count, test health summary (CRITICALs resolved, WARNINGs deferred), and deferred non-blocker issues. Produced with Skill 32 (GitHub Issue Operations). Stage 2 — Published: The approved draft becomes the body of `gh release create --target {merge_sha}`. The resulting GitHub Release is the artifact's published form, discoverable via the repository's Releases page. Transition: the draft advances to published only on explicit human approval ("release" keyword at the human gate in the close activity). Consumed by: stakeholders and next-iteration scope review (Orient & Validate Scope, Activity 140).
Change Reconciliation Document	Document	Process Change Request Build Feature	Required	0	Read the 'Change Reconciliation Document' artifact from playbook 'Junior Edda'. Type: Document. Required: true. OUTPUT: docs/plans/{FEAT}_CHANGE_RECONCILIATION.md Produced by Process Change Request (Activity 103) in Build Feature workflow. Purpose: reconciliation matrix, drift analysis, open questions, and proposed spec diffs for an approved change request. When scope changes mid-sprint, complete Process Change Request before EST-08 rebaseline. Does not replace PIN manifest — reconciles spec layers before separate replanning.
MCP FastMCP Reference Architecture	Document	Define MCP Architecture Define Architecture	Optional	0	Read the 'MCP FastMCP Reference Architecture' artifact from playbook 'Junior Edda'. Type: Document. Required: false. # MCP / FastMCP Reference Architecture Artifact ID: 57 Type: Document (Reference) Required: False Produced By Activity ID: DTA (integration & API section of SAO) Consumers: DTA → SAO authors; BPE plans that implement MCP ## Description Portable blueprint for adding MCP to a Django application with FastMCP. Use during DTA; copy chosen modules into the project SAO. Peer to artifacts 53 (INFRA), 54 (CICD), 56 (AI Agent). Out of scope: in-app agent loops (artifact 56); project-specific package maps and domain write pipelines. --- # 0. Purpose & How to Use ## 0.1 What this is A modular catalog for MCP on Django. Modules are optional unless the mission requires them. Dependencies are explicit so you assemble a stack without inventing glue. ## 0.2 DTA workflow 1. Answer mission questions (§1). 2. Pick Case A, Case B, or both (§2). 3. Treat tool descriptors as part of the contract (§3) — not polish. 4. Design payload discipline — filters, limits, batch tools (§4). 5. Choose transport topology (§5) — process model first, URL second. 6. Copy modules + proof into the project SAO; implement via §8 slices. ## 0.3 Design principles - Services (or API) are truth — tools adapt; they do not own business rules. - Descriptors are the LLM UX — weak docstrings produce wrong calls. - Default-narrow, explicit-widen — list tools filter + limit; never dump unbounded history into the model. - Batch common "all matching X" intents — one scoped mutation, not N× update round-trips. - MCP is its own process — not a Django `urlpatterns` entry. - Async boundary is explicit — FastMCP is async; Django ORM is sync. - Stdout is sacred on stdio — logs go to file or stderr only. - Prove with real calls — Client, direct tool, or process JSON-RPC. --- # 1. Mission Assessment \| # \| Question \| Drives \| \|---\|----------\|--------\| \| Q1 \| Consumers: local IDE only, or remote AI clients too? \| stdio vs HTTP/SSE sidecar \| \| Q2 \| Must MCP run without Django/ORM in-process? \| Case B \| \| Q3 \| Is there a stable token-authenticated DRF API? \| Case B cost \| \| Q4 \| Same rules for Web, REST, and MCP? \| Shared services (always) \| \| Q5 \| Auth: process user, PAT per call, or both? \| Identity module \| \| Q6 \| Should end users avoid putting DB credentials in the IDE? \| Distributable facade image (Case B) \| \| Q7 \| Do tools compose multiple API calls / side effects? \| Facade orchestration vs fat service methods \| \| Signal \| Prefer \| \|--------\|--------\| \| Local Django + IDE, fastest path \| Case A \| \| Public/minimal MCP image, no ORM \| Case B \| \| Both local speed and distributable client \| Hybrid (A + B, aligned signatures) \| \| API immature \| Case A first; extract B later \| \| Need parity audit tool↔endpoint \| Case B + mapping table \| --- # 2. Two Integration Cases ```mermaid flowchart LR subgraph caseA [CaseA_ServiceBridge] CA[AI_Client] --> FA[FastMCP] FA --> ST[sync_to_async] ST --> SV[services.py] SV --> ORM[Django_ORM] end subgraph caseB [CaseB_APIFacade] CB[AI_Client] --> FB[FastMCP] FB --> HX[httpx] HX --> API[DRF_API_endpoints] API --> SVB[services.py] end ``` ## 2.1 Case A — Direct bridge to services \| \| \| \|--\|--\| \| When \| MCP may load Django; lowest latency; API may lag the tool surface \| \| How \| Thin `@mcp.tool` wrappers call `_service` methods via `sync_to_async` \| \| Guidance* \| No business rules in tools; return JSON-safe dicts only; enforce authz inside services \| \| Integration \| Same services as views/ViewSets; `manage.py mcp_server` (or equivalent) after `django.setup()` \| ```python # Pattern: register_tools(mcp) per domain module @mcp.tool() async def list_items(, user_id: str, active_only: bool = True) -> dict: """See §3 for full descriptor requirements.""" return await sync_to_async(_list_items, thread_sensitive=True)( user_id=user_id, active_only=active_only ) ``` Layout:* ``` mcp/ server.py # FastMCP singleton, initialize_mcp() context.py # optional: contextvars current user tools/ <domain>_tools.py # register_tools(mcp) or plain functions management/commands/ mcp_server.py # stdio entry; no stdout noise ``` ## 2.2 Case B — Facade over DRF \| \| \| \|--\|--\| \| When \| Separate process/container; no ORM in MCP image; reuse API validation/auth \| \| How \| Sync tools call `httpx` with `Authorization: Token\|Bearer …`; map status → exceptions \| \| Guidance \| Keep tool names and signatures aligned with Case A if both exist; prefer a dedicated `@action` when composition needs a transaction \| \| Integration \| Depends only on base URL + token; OpenAPI helps humans, descriptors help models \| ```python def create_item(name: str, category: str) -> dict: """See §3 for full descriptor requirements.""" r = get_client().post("/api/items/", json={"name": name, "category": category}) return check_response(r, "create_item") ``` Layout: ``` mcp_facade/ server.py # argparse: --server, --token, --transport client.py # shared httpx.Client + check_response tools_http.py # one tool → one or more endpoints Dockerfile.mcp # fastmcp + httpx only ``` Composition: a tool may call several endpoints (create + link) or API + local FS (export then write files). Document partial-failure behavior; push true transactions into the API. ## 2.3 Hybrid Two adapters, one tool contract (names, params, errors, return shapes). Case A for in-process/local; Case B for the public image. Do not fork descriptors. --- # 3. Tool Descriptors — The LLM Contract Tool descriptors are not documentation polish. They are the primary interface the model uses to choose tools and fill arguments. FastMCP turns type hints into JSON Schema and surfaces the docstring to the client. A vague docstring is a broken API: wrong tool selection, hallucinated parameters, wasted retries. Concrete examples in the docstring are what make correct first calls the default. Invest here before adding more tools. ## 3.1 What the model sees \| Source \| Becomes \| \|--------\|---------\| \| Function name \| Tool name \| \| Type hints (`Literal`, defaults, `Optional`) \| JSON Schema constraints \| \| Docstring body \| Tool description text \| \| Param docs with examples \| Guidance for argument values \| \| Return / raises docs \| Expectations after the call \| ## 3.2 Required elements 1. Verb-led name matching intent (`list_`, `create_`, `get_`). 2. Opening sentence: what* it does and when to use it. 3. Sentence or clause: when not to use it (if a sibling tool exists). 4. Every param: type + meaning + Example: value. 5. Return: field list + Example: payload. 6. Raises: what the model should do next (`ValueError` → fix args; `PermissionError` → stop/ask user). 7. For nested structures (`list[dict]`): a full example object in the docstring. ## 3.3 Bad vs good ### Pair 1 — Vague CRUD Bad (model will invent fields): ```python @mcp.tool() async def update_item(id: int, data: dict) -> dict: """Update item.""" ... ``` Good: ```python @mcp.tool() async def update_item( item_id: int, name: str \| None = None, category: str \| None = None, status: Literal["draft", "active"] \| None = None, ) -> dict: """ Update a draft item. Pass only fields to change. Do not use for released items — create a change proposal instead. :param item_id: Item primary key. Example: 42 :param name: New display name, or omit. Example: "React Patterns" :param category: Taxonomy bucket, or omit. Example: "frontend" :param status: "draft" or "active", or omit. Example: "draft" :return: Updated item. Example: {"id": 42, "name": "React Patterns", "category": "frontend", "status": "draft", "version": "0.2"} :raises ValueError: unknown id, empty name, or duplicate name :raises PermissionError: item is released or caller is not owner """ ... ``` ### Pair 2 — Nested batch payload Bad (model guesses key names and date formats): ```python @mcp.tool() async def create_log_entries(user_id: str, entries: list) -> dict: """Create log entries.""" ... ``` Good: ```python @mcp.tool() async def create_log_entries(, user_id: str, entries: list[dict]) -> dict: """ Batch-create time-log entries for a day. Prefer direct foreign keys (imperative_id / objective_id) over legacy linked_to_ fields. :param user_id: Username. Example: "denis.petelin" :param entries: List of entry dicts. Each entry supports: - when: ISO-8601 UTC. Example: "2026-01-26T14:30:00Z" - duration: HH:MM:SS. Example: "02:00:00" - subject: Short label. Example: "Architecture work" - imperative_id: Optional link. Example: "3" - energy / mood: Optional 1–5. Example: 4 :return: {"status": "ok", "created": [<entry dicts>]} :raises ValueError: invalid duration, unknown ids, or empty entries Example: entries = [{ "when": "2026-01-26T14:30:00Z", "duration": "02:00:00", "subject": "Architecture work", "imperative_id": "3", "energy": 4, "mood": 4 }] """ ... ``` ### Pair 3 — Enums and disambiguation Bad (two similar tools; free-form status): ```python @mcp.tool() async def list_playbooks(status: str = "all") -> list: """List playbooks.""" ... @mcp.tool() async def list_all_playbooks() -> list: """Get playbooks for user.""" ... ``` Good (one tool, constrained filter, clear scope): ```python @mcp.tool() async def list_playbooks( status: Literal["draft", "released", "active", "all"] = "all", ) -> list: """ List playbooks visible to the current user (owned + shared), newest first. Use get_playbook when you already know the id and need nested workflows. :param status: Filter. Example: "draft". Use "all" for no filter. :return: List of summaries. Example: [{"id": 1, "name": "React Dev", "status": "draft", "version": "0.1"}] :raises ValueError: if no user context is configured """ ... ``` ## 3.4 Merge gate Before merging a tool, an engineer or agent must successfully call it from an IDE using only `tools/list` output — not the Python source. If they cannot, the descriptor failed. List tools additionally fail the gate if they lack a documented default filter and a hard `limit` (or cursor). Batch tools fail if scope is unbounded (no filter and no id list). --- # 4. Payload Discipline: Filters, Pagination, Batch Tools MCP tool results are model context, not a UI table. An unbounded `list_` that returns years of history can be thousands of lines: token blow-up, truncated JSON, IDE/client timeouts that look like "hangs", and agents that retry or loop on partial data. Default-narrow, explicit-widen.* ## 4.1 Why filters and limits are mandatory \| Failure mode \| What happens \| \|--------------\|--------------\| \| No filter, no limit \| Entire table serialized into the tool result \| \| Huge payload \| Context window fills; later reasoning degrades or the call times out \| \| Agent "fixes" it wrong \| Calls the same list again, or pages manually with broken offsets \| \| N× follow-up updates \| Each row update re-sends context; cost and latency explode \| Therefore every list-style tool needs: 1. Common-case filters that match how users actually speak ("today", "active only", "this week"). 2. A hard `limit` (or page cursor) with a safe default and a server-side max. 3. `total_count` (and ideally `filters_applied`) so the model knows to narrow the query or fetch another page — instead of assuming "this is everything." Prefer a summary tool (`get_day_summary`, `get_today`) when the question is "how is today?" — do not dump full history by default. ## 4.2 How — common-case filters and pagination Bad (will hang real deployments once data grows): ```python @mcp.tool() async def list_log_entries(, user_id: str) -> dict: """List all log entries for the user.""" ... ``` Good* (filters first, `limit` default, `total_count` back): ```python @mcp.tool() async def list_log_entries( , user_id: str, date: str \| None = None, week_id: str \| None = None, objective_id: str \| None = None, imperative_id: str \| None = None, search: str \| None = None, limit: int = 100, ) -> dict: """ List log entries with filters. Always pass the narrowest filter you can (prefer date or week_id). Default limit is 100; raise only if total_count shows you need another slice. :param user_id: Username. Example: "denis.petelin" :param date: ISO date filter. Example: "2026-01-02" :param week_id: Week id filter. Example: "1" :param objective_id: Objective id filter. Example: "5" :param imperative_id: Imperative id filter. Example: "3" :param search: Subject substring. Example: "meeting" :param limit: Max rows to return (default 100, server max 500). Example: 50 :return: {"log_entries": [...], "total_count": 240, "filters_applied": {...}} """ ... ``` Common-case filter patterns* (teach these in descriptors): \| Pattern \| Example tool shape \| User phrase it serves \| \|---------\|-------------------\|------------------------\| \| Boolean default \| `list_intents(..., active_only=True)` \| "my intents" → not archived junk \| \| Date / due \| `list_objectives(..., due_date="2026-02-06")` \| "today's tasks" \| \| Multi-dim + limit \| `list_log_entries(date=…, limit=100)` \| "what did I log this week?" \| \| Small backlog cap \| `get_backlog_objectives(..., limit=10)` \| "what's in the backlog?" \| Guidance: - Name the top ~3 user phrases as real parameters — not a single opaque `q: str` if you can avoid it. - Cap `limit` server-side (typical default 10–100; hard max 100–500 by entity density). - Return `total_count` even when truncated so the model can refine filters. - Case B: forward the same query params to DRF; unwrap `{results, count}` and expose `total_count` in the tool return — do not silently drop pagination metadata. - Cursor/`offset` is fine when `limit` alone is not enough; document the paging params in the docstring with examples. ## 4.3 Why batch tools — filter then mutate once User intent: "Reschedule all today's tasks to tomorrow." Bad agent path (common without batch tools): 1. `list_objectives(due_date=today)` → 25 rows (already large if unfiltered history was used). 2. Twenty-five `update_objective(id, due_date=tomorrow)` calls. 3. N round-trips, N partial failures, context thrash — slow and fragile. Good path: 1. Optional confirm: `list_objectives(due_date=today)` with a small `limit` / count. 2. One batch tool scoped by the same common-case filter (or by ids from that list). Flow: user intent → filtered list → one batch mutation → summary (`updated_count`). ### Two batch styles \| Style \| Signature idea \| When \| \|-------\|----------------\|------\| \| Filter-scoped (preferred for NL) \| `reschedule_objectives(from_due_date=…, to_due_date=…)` \| User named a set ("all today") \| \| Id-list \| `update_objectives(ids=[…], due_date=…)` \| Model already listed and selected ids \| Ship list tools with common-case filters (`list_objectives(due_date=…)`) and batch create (`create_log_entries(entries=[…])`) first; add the mutation twin when journeys say "all matching X". ### Good batch descriptor (illustrative) ```python @mcp.tool() async def reschedule_objectives( , user_id: str, from_due_date: str, to_due_date: str, completed: bool = False, ) -> dict: """ Move all objectives with from_due_date to to_due_date in one call. Use instead of calling update_objective per row. Only incomplete objectives are moved unless completed=True. :param user_id: Username. Example: "denis.petelin" :param from_due_date: Source due date YYYY-MM-DD. Example: "2026-02-06" :param to_due_date: Target due date YYYY-MM-DD. Example: "2026-02-07" :param completed: Include completed items (default False) :return: Summary only — not the full list. Example: {"updated_count": 12, "from_due_date": "2026-02-06", "to_due_date": "2026-02-07", "sample_ids": ["41", "42", "43"]} :raises ValueError: invalid dates, or zero matches when caller expected some """ ... ``` ### Batch anti-patterns - List-all (no filter) then loop `update_` per row. - Batch with neither filter nor ids (accidental full-table update). - Batch that returns the entire updated collection — return `updated_count` + sample ids; offer a filtered list if the user wants detail. ## 4.4 Payload merge gate - List tool: documented common-case filter(s) + default `limit` + `total_count` in the return shape. - Batch tool: explicit scope (filter and/or ids); refuses unbounded "all rows"; returns a summary. - "All matching X" appears in a user journey → batch mutate is required, not optional polish. --- # 5. Transport & Process Topology MCP is not mounted through Django's URL router. Reference implementations run FastMCP as a separate process. A public path like `/mcp` is a reverse-proxy concern, not a `path("mcp/", …)` view. Topology (summary): local IDE → stdio → MCP process → services (Case A) or API (Case B); remote clients → reverse proxy → MCP process over HTTP/SSE. ## 5.1 Recommended patterns \| Pattern \| Wiring \| Use \| \|---------\|--------\|-----\| \| Stdio \| `mcp.run(transport="stdio", show_banner=False, log_level="ERROR")` from a manage command or `__main__` \| Local IDE (Cursor, Claude Desktop) \| \| HTTP sidecar \| Separate process: `mcp.run(transport="http", host=…, port=…)` or uvicorn on `mcp.http_app()` \| Remote / cloud AI clients \| \| Legacy SSE sidecar \| `mcp.run(transport="sse", host=…, port=…)` \| Older clients that still speak SSE \| \| Public `/mcp` URL \| nginx/ALB forwards `/mcp` → MCP process port; disable response buffering for streams \| Friendly cloud URL without Django \| Case A local: one process loads Django + FastMCP (stdio). Case B remote: MCP process has no Django; only httpx → API. Cloud "same host": still two processes (web + MCP); proxy joins them on one hostname. ## 5.2 Do not do this ```python # WRONG — MCP is not a Django view urlpatterns = [ path("mcp/", somehow_fastmcp), # does not work as people hope ] ``` Reasons: FastMCP's HTTP stack is ASGI (Starlette), needs its own lifespan/session manager, conflicts with WSGI, and fights Django middleware/auth assumptions. Production deployments use a sidecar process, not Django URL routing. ## 5.3 Proxy sketch (public `/mcp`) ```nginx location /mcp/ { proxy_pass http://127.0.0.1:8001/; # MCP sidecar proxy_http_version 1.1; proxy_set_header Connection ""; proxy_buffering off; # required for SSE/streamable HTTP proxy_read_timeout 3600s; } ``` Health: expose a small `/health` on the MCP process for container probes (facade pattern). ## 5.4 Advanced — Starlette mount (not Django urls) FastMCP can build an ASGI app and mount it in Starlette/FastAPI: ```python from starlette.applications import Starlette from starlette.routing import Mount from fastmcp import FastMCP mcp = FastMCP("App") mcp_app = mcp.http_app(path="/") # Streamable HTTP app = Starlette( routes=[Mount("/mcp", app=mcp_app)], lifespan=mcp_app.lifespan, # required — nested lifespans are not picked up ) # run: uvicorn module:app ``` Use this when the outer app is already Starlette/FastAPI. Gluing the same into Django ASGI (Channels/`get_asgi_application` + Mount) is possible in theory and painful in practice (lifespan merge, workers, sync ORM). This RA recommends the sidecar instead. Prefer Streamable HTTP (`http` / `http_app`) for new work; keep `sse` only for legacy clients. --- # 6. Sync ↔ Async & Stdio Hygiene ## 6.1 Async boundary (Case A) FastMCP invokes tools on an async event loop. Django ORM is sync. \| Rule \| Detail \| \|------\|--------\| \| Wrap sync work \| `await sync_to_async(fn, thread_sensitive=True)(...)` \| \| One unit of work \| Prefer one sync helper over many tiny awaits \| \| Prefetch inside sync \| `select_related` / `list(qs)` before returning to async \| \| JSON-safe returns \| dict/list/primitives only; no model instances; stringify Decimals \| \| Contextvars \| `get_current_user()` usually needs `sync_to_async` from async tools \| \| Escape hatch \| `DJANGO_ALLOW_ASYNC_UNSAFE=true` hides errors; do not treat as architecture \| Case B sync tools avoid the ORM problem entirely — a reason facade images stay simple. ## 6.2 Stdio hygiene On stdio transport, stdout is the protocol. - Suppress Django setup prints (redirect during `django.setup()`). - Remove console `StreamHandler`s; log to file and/or stderr. - `requires_system_checks = []` on the manage command. - `show_banner=False`, quiet FastMCP log level. - Never `print()` or `self.stdout.write()` in the hot path. --- # 7. Testing Tools Use at least two tiers. \| Tier \| How \| Proves \| \|------\|-----\|--------\| \| T1 Client \| `async with Client(transport=mcp) as c: await c.call_tool(...)` \| Schema, registration, async path \| \| T2 Direct \| `await create_item(...)` (or sync facade fn) + real DB/API \| Service/API wiring \| \| T3 Process \| Subprocess JSON-RPC `initialize` → `tools/list` → `tools/call` \| Entrypoint + stdio cleanliness \| T1 recipe — FastMCP Client (proves schema, registration, async path): ```python from fastmcp.client import Client @pytest.fixture async def mcp_client(): # `mcp` is the FastMCP server instance imported from your server module async with Client(transport=mcp) as client: yield client @pytest.mark.asyncio @pytest.mark.django_db async def test_list_items(mcp_client): result = await mcp_client.call_tool( name="list_items", arguments={"user_id": "test.user", "active_only": True}, ) assert "items" in result.data @pytest.mark.asyncio @pytest.mark.django_db async def test_tool_names_registered(mcp_client): tools = await mcp_client.list_tools() tool_names = [t.name for t in tools] assert "list_items" in tool_names assert "create_item" in tool_names @pytest.mark.asyncio @pytest.mark.django_db async def test_validation_error_is_actionable(mcp_client): # Blank required field must return a clear ValueError message, not a 500 with pytest.raises(Exception, match="name"): await mcp_client.call_tool("create_item", arguments={"user_id": "test.user", "name": ""}) ``` Also assert: Case B bad/missing token fails cleanly (403/401, not 500). --- T2 recipe — Direct service call (proves service/ORM wiring, no MCP overhead): ```python import pytest from myapp.services import ItemService # adjust import to your project @pytest.mark.django_db def test_create_item_persists(django_user_model): user = django_user_model.objects.create_user(username="test.user", password="pw") svc = ItemService() item = svc.create(user_id=user.pk, name="Widget", active=True) assert item.pk is not None assert item.name == "Widget" @pytest.mark.django_db def test_list_items_returns_active_only(django_user_model): user = django_user_model.objects.create_user(username="test.user2", password="pw") svc = ItemService() svc.create(user_id=user.pk, name="Active", active=True) svc.create(user_id=user.pk, name="Inactive", active=False) results = svc.list(user_id=user.pk, active_only=True) assert all(r["active"] for r in results) assert len(results) == 1 ``` T2 uses the real DB (`@pytest.mark.django_db`), no mocks, no MCP transport. It is fast and runs without the async overhead of T1. --- T3 recipe — Subprocess JSON-RPC (proves entrypoint boots cleanly, no stdout noise): Required when stdio transport is selected. Verifies that the server process emits only valid JSON on stdout. ```python import json import subprocess import sys def _send(proc, payload: dict) -> dict: line = json.dumps(payload) + "\n" proc.stdin.write(line.encode()) proc.stdin.flush() return json.loads(proc.stdout.readline()) def test_mcp_server_stdio_clean(): proc = subprocess.Popen( [sys.executable, "-m", "myapp.mcp.server"], # adjust to your entrypoint stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, ) try: # Step 1: initialize handshake resp = _send(proc, { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "0"}}, }) assert resp.get("result", {}).get("protocolVersion") is not None, "initialize failed" # Step 2: list tools resp = _send(proc, {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}) tool_names = [t["name"] for t in resp["result"]["tools"]] assert "list_items" in tool_names # Step 3: call a read tool resp = _send(proc, { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "list_items", "arguments": {"active_only": False}}, }) assert "error" not in resp, f"tool call failed: {resp}" # Step 4: verify no stray stdout noise before/between responses # (all non-JSON stdout would have broken json.loads above) finally: proc.terminate() proc.wait() stderr_output = proc.stderr.read().decode() # Logging goes to stderr — that is fine; assert it is not empty only if you expect startup logs assert "Traceback" not in stderr_output, f"server crashed:\n{stderr_output}" ``` Key assertion: if any `print()` or Django startup message reached stdout, `json.loads` would have raised before reaching this point — so passing the test proves stdout is clean. --- # 8. Modules, Profiles, Proof, Slices ## 8.1 Module map \| ID \| Module \| Role \| \|----\|--------\|------\| \| M1 \| Transport \| stdio and/or HTTP/SSE sidecar \| \| M2 \| Server core \| FastMCP instance, lifecycle, logging \| \| M3 \| Tool surface \| Names, schemas, descriptors, filters/limits/batch (§4) \| \| M4a \| Service adapter \| Case A → `services.py` \| \| M4b \| HTTP adapter \| Case B → DRF via httpx \| \| M5 \| Identity \| Process user / PAT / `who_am_i` \| \| M6 \| Error contract \| `ValueError` / `PermissionError` / 5xx mapping \| \| M7 \| Test harness \| T1–T3 \| \| M8 \| Distribution \| manage command and/or Docker facade \| \| M9 \| Parity (Case B) \| Tool ↔ endpoint map \| Deps: M3 → exactly one of M4a/M4b per process; M4a → services → ORM; M4b → HTTP → API → services; M2 → M1+M3+M5+M6. Forbidden: tools → models; facade → ORM. ## 8.2 Profiles \| Profile \| Modules \| When \| \|---------\|---------\|------\| \| Desktop A \| M1 stdio, M2, M3, M4a, M5, M6, M7, M8 manage \| Single-user local \| \| Facade B \| M1 HTTP/SSE, M2, M3, M4b, M5 token, M6, M7, M8 Docker, M9 \| Public image / no ORM \| \| Hybrid \| Desktop A + Facade B, shared tool contract \| Local + distributable \| ## 8.3 Integration proof (DoD) 1. `tools/list` matches the contracted set. 2. Happy path via T1 or T3. 3. Auth failure controlled (bad token / missing user). 4. Validation → actionable `ValueError`. 5. Mutations go through services (assert side effects). 6. Stdio session: no banner/log pollution on stdout. 7. Facade (if any): runs with base URL + token only. 8. Descriptor gate (§3.4) passed for every new tool. 9. Payload gate (§4.4): list tools filter+limit+`total_count`; batch tools scoped; no unbounded dumps. ## 8.4 Build slices \| Slice \| Deliverable \| \|-------\|-------------\| \| S0 \| Mission answers + profile in SAO \| \| S1 \| Server core + logging hygiene + empty registry \| \| S2 \| First read tool + full descriptor + filters/`limit` + T1/T2 \| \| S3 \| First write tool through service/API + error contract \| \| S4 \| Expand by bounded context; registration count test \| \| S5 \| Batch mutate when journey says "all matching X" (filter→batch) \| \| S6 \| (Hybrid/B) facade + Docker + proxy `/mcp` + T3 \| \| S7 \| Parity table (Case B); IDE smoke on descriptors + payload gate \| --- Generic reference. Project SAOs adapt modules and name their write-policy constraints; they do not belong in this artifact.
AI Agent Reference Architecture	Document	Define AI Agent Architecture Define Architecture	Optional	0	Read the 'AI Agent Reference Architecture' artifact from playbook 'Junior Edda'. Type: Document. Required: false. # AI Agent Reference Architecture Artifact ID: 56 Type: Document Required: False ## Description # AI Agent Reference Architecture Artifact ID: 56 Type: Document (Reference) Required: False Produced By Activity ID: 200 (Define AI Agent Architecture) Consumers: DTA-19 → SAO §17; BPE-01 agent feature planning Portable, single-file blueprint: confirm components → pick patterns → choose serving mode → tick capabilities → copy code blocks → wire → test. --- # How to use this document Audience: Solution architects and implementers running DTA-19 (Define AI Agent Architecture) and filling SAO §17. Workflow: 1. Read Part 1 — Components and confirm infra, model, optional vector tier, framework packages, memory tiers, and observability baseline. 2. Pick one or more Part 2 — Design patterns; each pattern lists required SC-xx scenarios and CAP-xxx bundles. 3. Choose Part 3 — Serving mode (real-time chat, batch/queue, or both). 4. Tick capabilities in Part 4.1 Capability table; copy matching Part 4.2 Capability specifications into your repo. 5. Wire packages per Part 4.3 Module wiring; start from the closest Part 4.4 Assembly template. 6. Prove integration with Part 4.5 Integration proof tests before release. Rules: - Select capabilities (`CAP-xxx`), not modules — modules are package-location hints only. - Every CAP spec is self-contained; no external codebase is required to understand it. - Delete CAP blocks you did not select; the only allowed LLM mock is CAP-004 ScriptedLLM. - Structured JSON from LLM (bootstrap, discovery, map/extract) → Pattern 2 / SC-02 + CAP-008 + CAP-009 mandatory. - Unsure which pattern? Use Part 5 — Quick reference decision trees. - Large domain state in chat → CAP-037 snapshot + CAP-039 dual tool exposure. - Need memory beyond a hot snapshot → Component 5 — Memory tier decision tree before CAP-091–094. - Background plan/worker selected → never execute pre-defined steps as dumb scripts — see Pattern 4 · Anti-patterns. - Production agent → CAP-101 interaction trace (`correlation_id` + normalized usage/cost/latency at CAP-001 boundary). - Dual path CAP-037–039: required when domain state is large; default in T-01; optional in bare SC-01 minimum. - Background steps that call the LLM → include CAP-053, CAP-054, CAP-066 (mandatory when worker runs LLM per step; see Pattern 4 anti-patterns). Reference implementation note: Code samples use Django ORM and Celery as the reference stack. Substitute equivalent transaction-commit hooks and a task broker in other frameworks — preserve the contracts (on_commit enqueue, acks_late, durable plan rows). --- # Part 1 — Agentic architecture and key components ## 1.0 Architecture overview Agentic systems stack infrastructure, model access, optional retrieval, orchestration packages, memory, design patterns, serving modes, and observability. Components are composable — pick only what your patterns require. ```text Infra (env, secrets, broker) → Model layer (BaseLLM, adapters, tiers) → Vector tier (optional — embeddings + index) → Framework packages (factory, loop, plan, worker, tools, …) → Memory tiers (snapshot, semantic, profile, notes, reference library) → Design patterns (Part 2) → Serving mode (Part 3 — real-time and/or batch) → Observability (correlation_id, SSE, usage/cost trace) ``` Pattern ↔ component matrix \| Pattern \| Infra \| Model \| Vector \| Framework \| Memory \| Observability \| \|---------\|:-----:\|:-----:\|:------:\|:---------:\|:------:\|:-------------:\| \| 1 Prompt framework \| ✓ \| ✓ \| — \| prompt/ \| — \| optional \| \| 2 RAG & structured extract \| ✓ \| ✓ \| ✓ \| tools/, worker/ \| Tier 4 \| optional \| \| 3 Multi-agent communication \| ✓ \| ✓ \| — \| events/, loop/ \| optional \| ✓ \| \| 4 Conversational agents + roles \| ✓ \| ✓ \| optional \| loop/, plan/, worker/, context/ \| Tier 1–3 \| ✓ \| \| 5 Function calling & tool agents \| ✓ \| ✓ \| — \| tools/, loop/ \| — \| ✓ \| \| 6 Tool protocols (MCP, A2A, ACP) \| ✓ \| ✓ \| — \| tools/, external MCP \| — \| ✓ \| \| 7 Compiled pipeline \| ✓ \| ✓ \| — \| plan/, worker/ \| — \| optional \| --- ## 1.1 Component 1 — Infra layer The infra layer supplies environment configuration, secret handling, LLM provider readiness, and (when async plans are used) message broker + result backend. Agents must fail fast when infra is misconfigured — never silently fall back to wrong models or missing credentials. ### Environment contract \| Variable \| Purpose \| Required when \| \|----------\|---------\|---------------\| \| `LLM_PROVIDER` \| Adapter selection: `anthropic`, `openai`, `ollama`, … \| Always \| \| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` \| Cloud provider auth \| Matching provider \| \| `OLLAMA_HOST` \| Base URL for local Ollama (default `http://127.0.0.1:11434`) \| `LLM_PROVIDER=ollama` \| \| `LLM_OLLAMA_MODEL` \| Default Ollama model tag \| Ollama provider \| \| `LLM_TIER_<NAME>` \| Maps named tier → model id (planning / execution / field) \| CAP-122 \| \| `CELERY_BROKER_URL` \| Task queue broker (or equivalent) \| CAP-060 \| \| `CELERY_RESULT_BACKEND` \| Task results store (or equivalent) \| CAP-060 \| \| `CORRELATION_ID_HEADER` \| HTTP header name (default `X-Correlation-ID`) \| CAP-101 \| ### Ollama readiness Before accepting traffic with `LLM_PROVIDER=ollama`: 1. Confirm Ollama daemon is running on `OLLAMA_HOST`. 2. Probe `GET {OLLAMA_HOST}/api/tags` or `GET {OLLAMA_HOST}/api/ps` — non-200 → fail startup (do not queue requests against a dead local LLM). 3. Verify configured model tag appears in `/api/tags`; if missing, log explicit pull instruction (`ollama pull <model>`). 4. Health endpoint on your API should surface LLM readiness separately from DB readiness. ### Secrets policy - API keys live server-side only — environment variables or secret manager; never in frontend bundles, MCP stdio client env exposed to IDE extensions without review, or committed config. - Tool calls that mutate data must receive server-injected identity (CAP-036) — never trust client-supplied user ids for writes. - Log redaction: never log full API keys or raw tool payloads containing secrets. ### Worker infra checklist (SC-01 / SC-03) When background plan execution is selected: - [ ] Broker reachable from worker process - [ ] `acks_late=True` and visibility timeout > max task duration (CAP-063) - [ ] Result backend sized for plan metadata (not full LLM transcripts unless required) - [ ] Beat/cron for orphan recovery if CAP-064 selected - [ ] Rate-limit handling: CAP-061 dual-layer 429 (in-call backoff + job `waiting_retry`) --- ## 1.2 Component 2 — Model layer The model layer isolates vendor SDKs behind a provider-agnostic port. All agent code depends on CAP-001 `BaseLLM`, not Anthropic/OpenAI/Ollama directly. Core responsibilities: \| Concern \| CAP-IDs \| Notes \| \|---------\|---------\|-------\| \| Single completion entry \| CAP-001 \| `complete(messages, system, tools?, …) -> LLMResponse` \| \| Tool-calling generate \| CAP-002 \| Normalized `tool_calls` list in response \| \| Token streaming \| CAP-003 \| Iterator/stream for live UI \| \| Test seam \| CAP-004 \| ScriptedLLM — only allowed LLM mock \| \| Retry / backoff \| CAP-005, CAP-006 \| Exponential backoff + status callback \| \| Extended thinking \| CAP-007, CAP-008 \| Provider reasoning budget; adapter splits thinking vs content \| \| Structured JSON extract \| CAP-009 \| Strip fences; parse array/object — fail loud \| \| Prompt cache blocks \| CAP-010 \| Ephemeral cache on stable system layers \| \| Provider factory \| CAP-011 \| Select adapter from env \| \| Model tiers \| CAP-122 \| planning / execution / field mapping \| Implement adapters in `llm/adapters/`; wire via `build_llm_for_tier()` in factory (CAP-120). Full specs: Part 4.2. --- ## 1.3 Component 3 — Vector stores and embeddings Add a vector tier when semantic retrieval is required and brute-force JSON snapshots or SQL search are insufficient. When to add \| Signal \| Action \| \|--------\|--------\| \| Pattern 2 / SC-02 with document corpus \| Index chunks for `search_knowledge` (CAP-090 + CAP-094) \| \| Tier 2 semantic memory (CAP-091) \| Embed entity text fields or note bodies \| \| Snapshot exceeds token budget \| Query-time retrieval instead of full layer-4 dump \| Minimal interfaces ```python def embed_text(text: str, , model: str \| None = None) -> list[float]: ... class VectorIndex: def upsert(self, scope_id: str, doc_id: str, chunks: list[dict]) -> None: ... def query(self, scope_id: str, embedding: list[float], , limit: int = 20) -> list[dict]: ... ``` Backend comparison (pick one per deployment) \| Backend \| Best for \| Trade-offs \| \|---------\|----------\|------------\| \| pgvector (Postgres extension) \| Single-DB apps; transactional ingest \| Couples search to DB load \| \| Dedicated vector DB \| High QPS semantic search \| Extra service to operate \| \| In-process / dev index \| Local dev, tests \| Not durable; no horizontal scale \| Index lifecycle: ingest → chunk (fixed size + overlap) → embed → upsert metadata `{scope_id, doc_type, title, version}` → query at tool-call time. Re-ingest bumps version; CAP-090 searches latest index only. Wire CAP-090/091/094 specs in Part 4.2 when this component is selected. --- ## 1.4 Component 4 — Agent framework (internal orchestration) This architecture uses first-party packages — not LangChain, CrewAI, or AutoGen. Orchestration is explicit: factory composes LLM + tools + prompt; loop runs bounded ReAct; plan persists steps; worker executes async. Package map ```text llm/ CAP-001–011 Model port + adapters prompt/ CAP-020–023 Layered prompt stack tools/ CAP-030–036 Registry, envelope, HITL, guards context/ CAP-037–039 Snapshot + dual tool exposure loop/ CAP-040–044 Bounded ReAct + plan handoff plan/ CAP-050–055 Durable steps + synthesis chain worker/ CAP-060–066 Async execution + 429 handling blackboard/ CAP-070–073 Soft multi-turn intent learning/ CAP-080–081 Optional outcome capture knowledge/ CAP-090–094 RAG + memory tiers streaming/ CAP-100 SSE progress events events/ CAP-110 Domain event ingress observability/ CAP-101 Interaction trace factory/ CAP-120–122 Composition root + identities ``` Composition root (CAP-120): single place that constructs `PlannerAgent`, `FieldAgent`, or pipeline worker with injected dependencies. Forbidden imports - `tools/` must not import `loop/` - `llm/` must not import domain apps - `loop/` must not own business rules — calls tools only - `context/` must not import `loop/` or `worker/` - `observability/` must not import domain mutation paths — record only Full dependency matrix and diagram: Part 4.3. --- ## 1.5 Component 5 — Memory Stack memory tiers by access pattern — do not pick one strategy for everything. \| Tier \| Name \| When \| CAP-IDs \| Freshness \| \|------\|------\|------\|---------\|-----------\| \| 1 \| Hot snapshot \| SC-01 chat; domain fits structured JSON \| CAP-037, CAP-038, CAP-039 \| TTL cache; invalidate on mutation \| \| 2 \| Semantic retrieval \| Snapshot too large; NL lookup \| CAP-091 \| Query-time embedding search \| \| 3 \| AI-managed profile \| Persistent preferences across sessions \| CAP-092 \| Agent/user merge + audit \| \| 4 \| Reference library \| Books, playbooks, frameworks on demand \| CAP-094, CAP-090 \| Versioned docs + RAG index \| \| 5 \| Entity notes graph \| Recurring people, projects, topics \| CAP-093 \| Per-entity notes \| Decision tree ```text All state fits in one JSON snapshot (< ~25K tokens)? yes → Tier 1 only Need "find X in my history" without full snapshot? yes → add Tier 2 (CAP-091) Agent should remember user patterns across sessions? yes → add Tier 3 (CAP-092) User uploads reference docs / playbooks? yes → add Tier 4 (CAP-094) Recurring entities with free-form notes? yes → add Tier 5 (CAP-093) ``` Dual execution path (Tier 1 + SC-01): conversation mode hydrates snapshot into prompt layer 4 (CAP-037) and exposes mutation-only tools (CAP-039); plan worker uses full registry for reads and analysis (CAP-060 + CAP-044). Blackboard (optional): CAP-070–073 for soft multi-turn intent when the user steers without explicit tool calls — not a substitute for Tier 1 snapshot on large domains. --- ## 1.6 Component 6 — Observability Production agents require request-level traceability without locking to a single LLM vendor's dashboard. Correlation ID: generate at API entry (or honor inbound header); propagate through loop, worker tasks, tool executions, and SSE channel. Per-LLM-call record (CAP-101): at the CAP-001 adapter boundary, normalize `{input_tokens, output_tokens, latency_ms, estimated_cost}` into `AgentInteraction` rows keyed by `correlation_id`. SSE progress (CAP-100): typed events — `token`, `plan_step`, `plan_failed`, `rate_limit` — for real-time serving (Part 3.1). Key metrics to monitor \| Metric \| Why \| \|--------\|-----\| \| LLM latency p95 \| User experience / SLA \| \| Tokens per conversation \| Cost control \| \| Tool error rate \| Domain or schema drift \| \| Plan failure rate \| Worker or synthesis issues \| \| Queue depth / task age \| Worker capacity \| \| 429 retry count \| Provider quota planning \| \| Snapshot cache hit rate \| CAP-037 efficiency \| This is not a full AgentOps platform chapter — export these signals to your existing logs, metrics, and dashboards. --- # Part 2 — Design patterns Each pattern maps to SC-xx scenarios and CAP-xxx bundles. Copy the scenario card, tick CAPs in Part 4, wire the assembly template. --- ## Pattern 1 — Prompt framework When to use: Every agent — layered system prompt separates stable identity from dynamic context. When not to use: Never skip entirely; SC-02 may use a minimal two-layer stack. Required components: Model (CAP-001), Prompt (CAP-020–023), optional CAP-010 cache on stable layers. Scenario / CAP map \| SC \| Role \| CAP-IDs \| \|----\|------\|---------\| \| all \| Foundation + identity + recipe + dynamic context \| CAP-020, CAP-021 \| \| SC-01, SC-03 \| Workflow recipe layer \| CAP-022 \| \| SC-02, SC-03 \| Validate-before-LLM \| CAP-023 \| \| SC-01, SC-03 \| Prompt cache blocks \| CAP-010 \| Example flow: Factory builds `PromptBuilder().with_identity(identity).with_workflow(recipe).with_context(snapshot=…).build()` → passed as `system` to CAP-001. Assembly template: T-01, T-02, or T-03 (all include CAP-020). --- ## Pattern 2 — RAG and structured extract When to use: Batch ingest, bootstrap, or field extraction where LLM output is structured JSON driving domain writes (SC-02). When not to use: Pure conversational Q&A with no extract step (SC-01 only). Required components: Model (CAP-008, CAP-009), Vector tier optional (CAP-090, CAP-094), Tools (CAP-030, CAP-031). Scenario / CAP map — SC-02 · Field extractor / batch ingest Pick when: Fixed or batch input (repo snapshot, document, API payload) is ingested through a scripted step chain; one or more LLM steps emit structured JSON that drives domain writes; no ReAct chat loop. Typical flow (dual-tier): \| Step \| Type \| Responsibility \| \|------\|------\|----------------\| \| 1 Gather \| Domain pipeline (non-CAP) \| Scan input into raw candidates (deterministic) \| \| 2 D0 pre-filter \| Domain pipeline (non-CAP) \| Path/class/rules reject noise; merge duplicates on stable natural key \| \| 3 D1 canonicalize \| CAP-008, CAP-009 \| Planning-tier LLM batch: merge / reject / rename; parse failure must fail loud \| \| 4 Cleanup \| Domain pipeline (non-CAP) \| Deterministic post-LLM rules (externals, denylist, cardinality caps) \| \| 5 Propose writes \| Domain pipeline (non-CAP) \| Create/update/delete ops via domain service (often through SC-05 ChangeSet) \| Only D1 maps to CAP specs — Gather, D0, Cleanup, and Propose-writes are unit-testable product code in your domain package. Example flow: CLI scans a repo → D0 drops tests/fixtures → D1 LLM merges duplicates → service proposes ChangeSet → CLI exits with op counts. Not this if: User multi-turn chat steers the task (→ Pattern 4 / SC-01); steps are a fixed template graph with selective LLM nodes (→ Pattern 7 / SC-03). Often combined with: Pattern 5 / SC-05 when writes go through approval / confidence gates. CAP-IDs (required): 001, 004, 008, 009, 020, 030, 031, 120, 121, 122 CAP-IDs (optional): 005, 011, 023, 032, 036, 090, 091, 094 Starting template: T-02 Field --- ## Pattern 3 — Multi-agent communication When to use: Domain events should trigger agent messages or plans without the user opening chat first (SC-04). When not to use: All interactions start from user chat (→ Pattern 4 / SC-01). Required components: Events (CAP-110), Model (CAP-001, CAP-002), Loop (CAP-040), Factory (CAP-120), optional Plan/Worker (CAP-050, CAP-060). Scenario / CAP map — SC-04 · Event-driven nudge Pick when: Something happens in the domain (ChangeSet merged, SLA breach, stale graph) and the system proactively notifies or plans without the user opening chat first. Example flow: ChangeSet approved → event handler → short agent loop or enqueue plan → user gets notification or suggested next action. Not this if: Every interaction starts from user chat (→ SC-01); only batch extract (→ SC-02). CAP-IDs (required): 001, 002, 040, 110, 120 CAP-IDs (optional): 050, 060, 100, 101 Starting template: T-00 custom (CAP-110 + subset of SC-01 stack) Note: This pattern describes in-app event → agent wiring — not a full A2A wire protocol spec. External agent-to-agent buses (A2A, ACP) are covered in Pattern 6. --- ## Pattern 4 — Conversational agents and roles When to use: User opens chat, agent calls tools, work beyond one request becomes a background job (SC-01). Required components: Loop (CAP-040–044), Plan (CAP-050), Worker (CAP-060), Context (CAP-037–039 when domain is large), Identities (CAP-121, CAP-122). Scenario / CAP map — SC-01 · Conversational planner Pick when: A user opens chat (or equivalent UI), sends natural-language messages, and the app runs a tool-calling loop; work that outlives one request is handed to a background worker. Example flow: User: “Analyze auth module and propose a refactor plan” → agent calls read tools → creates durable plan → worker executes steps → user sees progress/completion. Not this if: Input is a batch file/CI job with no conversation (→ SC-02 or SC-03); the agent only proposes writes pending approval with no chat loop (→ SC-05, optionally plus SC-01). Dual execution path (recommended for large domain state): Chat uses CAP-037 snapshot in layer 4 + CAP-039 mutation-only tools. Plan worker (CAP-060) retains full read/analyze tools. Required when domain state is large; default in T-01; optional in bare SC-01 minimum. Hybrid worker (when background steps call LLM): Include CAP-053, CAP-054, CAP-066 — mandatory when worker runs an LLM per step; see anti-patterns below. CAP-IDs (required): 001, 002, 004, 020, 030, 031, 040, 044, 050, 051, 060, 062, 120, 121 CAP-IDs (optional): 003, 005, 006, 007, 010, 033, 037, 038, 039, 042, 043, 052, 053, 054, 061, 066, 070, 091, 092, 093, 100, 101 Starting template: T-01 Planner ### Anti-patterns (Pattern 4 + worker) Mechanical step execution Symptom: Worker runs pre-created `PlanStep` rows by parsing `action` strings and calling `ToolExecutor` without an LLM call per step. Fix: Hybrid worker execution (CAP-053 + CAP-054 + CAP-066): each step gets workflow prompt + prior synthesis; LLM chooses tools before advancing. Proof: PRF-SC01-06 Assuming chat loop recovers worker failures Symptom: Plan fails in background; user waits forever; chat agent unaware. Fix: CAP-100 SSE `plan_failed` event and/or inject failure context on next user message — CAP-040 does not auto-retry worker steps. Proof: PRF-SC01-07 --- ## Pattern 5 — Function calling and tool agents When to use: Agent proposes mutating or destructive writes; human approval required before commit (SC-05); or any scenario using tool registry. Required components: Tools (CAP-030–036), optional Loop (CAP-040). Scenario / CAP map — SC-05 · Governed mutations Pick when: The agent may call mutating or destructive tools but policy requires human approval before commit (HITL), with server-side identity on every tool call. Example flow: Agent suggests `delete_element` → tool parks action as pending → UI shows approve/reject → only on approve does the service execute. Often combined with: SC-01 or SC-02 (governance layer on top of planner or field agent). CAP-IDs (required): 001, 030, 031, 033, 036 CAP-IDs (optional): 040, 050, 032 Starting template: T-00 custom (CAP-033, CAP-036 + base scenario CAPs) ### SC-02 × SC-05 · Full rescan invariants Applies when: SC-02 performs a full rescan with delete ops and writes pass through SC-05. Invariant 1 — Confidence parity: Delete ops on rescan use the same auto-apply policy as adds/updates. Invariant 2 — Delete before create: When domain uses natural-key upserts, apply deletes before adds for the same rescan batch. Proof obligations: PRF-SC02-03, PRF-SC02-04, PRF-SC05-02. --- ## Pattern 6 — Tool protocols (MCP, A2A, ACP) When to use: External clients (IDE, remote agents) invoke tools via MCP; or you evaluate agent-to-agent buses for cross-system delegation. In-app vs external boundary \| Layer \| Responsibility \| \|-------\|----------------\| \| In-app `tools/` registry \| CAP-030–036; domain services; HITL \| \| External MCP server \| Transport, auth, tool listing for clients — see playbook artifact MCP FastMCP Reference Architecture \| \| A2A / ACP (conceptual) \| Use when agents are peers across systems with their own runtime — prefer async handoff + durable plan (CAP-050) over synchronous chat coupling \| When to choose MCP: IDE or third-party agent needs discoverable tools with stdio or HTTP+SSE transport. When to choose in-app registry only: Single deployed app with first-party UI — MCP optional. When to evaluate A2A/ACP: Multiple autonomous agents owned by different teams/services need standardized delegation — start with event + plan enqueue (Pattern 3) before adopting a full protocol stack. CAP-IDs: CAP-030, CAP-031, CAP-034 (schema); MCP server wiring is not duplicated here. --- ## Pattern 7 — Compiled pipeline When to use: A trigger (schedule, webhook, CI, domain event handler) runs a known step graph; only some steps call the LLM (SC-03). Required components: Plan (CAP-050), Worker (CAP-060), Model (CAP-001, CAP-002), Factory (CAP-120). Scenario / CAP map — SC-03 · Compiled pipeline Pick when: A trigger fires a known step graph; only some steps call the LLM. Example flow: CI merge → enqueue compiled plan → worker runs data step → LLM planning step → assessment step → publish artifact. Not this if: User multi-turn chat steers the task (→ SC-01); batch extract with D0/D1 chain (→ SC-02). CAP-IDs (required): 001, 002, 004, 020, 050, 051, 053, 060, 061, 062, 120 CAP-IDs (optional): 054, 066, 100, 101 Starting template: T-03 Pipeline --- # Part 3 — Serving modes Serving mode determines latency expectations, queueing, and progress reporting. Pick one or combine real-time + batch. > Out of scope for this artifact: Edge serving (on-device models), intelligent data pipelines, and full AgentOps platforms. Use Component 6 key metrics only. --- ## 3.1 Real-time serving Applies to: Pattern 4 / SC-01, Pattern 3 event nudges with live UI, Pattern 5 with chat. Characteristics: - Synchronous request thread runs CAP-040 bounded ReAct loop (default cap on iterations/tool calls). - CAP-003 streams tokens to client when chat UI supports partial render. - CAP-044 intercepts `create_plan` → enqueues worker → ends loop — user gets immediate ack while work continues async. - CAP-039 conversation mode keeps chat fast: snapshot reads in prompt, mutation-only tools exposed. - CAP-100 SSE channel publishes `token`, `tool_start`, `tool_end`, `plan_created` events keyed by `correlation_id`. Checklist - [ ] HTTP timeout > worst-case sync loop OR loop hands off to worker before timeout - [ ] Streaming flushes on token boundaries (avoid buffering entire completion) - [ ] Plan handoff returns `plan_id` to client for progress subscription - [ ] CAP-101 records each LLM call in the sync path --- ## 3.2 Batch and queued serving Applies to: Pattern 2 / SC-02 CLI ingest, Pattern 7 / SC-03 compiled pipelines, background portion of SC-01. Characteristics: - CAP-060 Celery (or equivalent task broker) executes `execute_plan(plan_id)` outside the request thread. - CAP-062 enqueues with `transaction.on_commit` (or equivalent post-commit hook) so plan rows exist before worker starts. - CAP-061 dual-layer 429: in-call backoff (CAP-005) plus job state `waiting_retry` + broker retry. - CAP-063–065 durability: `acks_late`, orphan recovery beat, stale `running` reset. - CAP-066 per-step model tier: planning steps use large model; data/assessment steps use cheap tier. - SC-02 exits with non-zero status on CAP-009 parse failure — never silent zero-op batch jobs. Checklist - [ ] Worker uses CAP-039 `mode=workflow` (full tool registry) - [ ] Idempotent step completion (CAP-052 atomic mark_started) - [ ] Batch CLI maps domain errors to exit codes for CI - [ ] Queue monitoring alerts on task age p95 --- ## 3.3 Observability for serving Bridges Component 6 with runtime events: \| Event \| Source \| Consumer \| \|-------\|--------\|----------\| \| `plan_step` \| CAP-100 / worker \| UI progress bar \| \| `plan_failed` \| CAP-100 / worker \| User notification; support triage \| \| `rate_limit` \| CAP-006 / CAP-061 \| Retry UI message \| \| LLM usage row \| CAP-101 \| Cost dashboards \| Wire once: middleware sets `correlation_id` → pass to `bounded_react_loop`, `execute_plan`, SSE publisher, and CAP-101 wrapper — same id end-to-end. Proof: PRF-OBS-01, PRF-SC01-07 --- # Part 4 — Capability appendix ## 4.1 Capability table Scan this table. Tick what you need. Find each CAP-ID in Capability specifications below. --- # Group A — LLM boundary (`llm/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| 001\| CAP-\| CAP-001 \| LLM Port protocol \| Single `complete()` entry; agents depend on protocol not vendor SDK \| llm \| — \| all \| 002\| CAP-\| CAP-002 \| Tool-calling generate \| LLM returns structured `tool_calls` alongside text \| llm \| 001 \| SC-01,03,04 \| 003\| CAP-\| CAP-003 \| Token stream \| Stream tokens to caller for live UI \| llm \| 001 \| SC-01 \| 004\| CAP-\| CAP-004 \| ScriptedLLM \| Replay queued responses in tests; only allowed mock seam \| llm \| 001 \| all \| 005\| CAP-\| CAP-005 \| LLM retry backoff \| Exponential backoff on rate limit / transient errors \| llm \| 001 \| SC-01,03 \| 006\| CAP-\| CAP-006 \| Retry status callback \| `(message, attempt, delay)` hook during backoff \| llm \| 005 \| SC-01 \| 007\| CAP-\| CAP-007 \| Extended thinking request \| Provider reasoning budget (`budget_tokens`) on planning calls \| llm \| 001 \| SC-01,03 \| 008\| CAP-\| CAP-008 \| Thinking response normalize \| Adapter splits `content` vs `thinking` at boundary \| llm \| 001 \| SC-02 \| 009\| CAP-\| CAP-009 \| Structured JSON extract \| Strip fences/tags; parse array/object from LLM output \| llm \| 008 \| SC-02 \| 010\| CAP-\| CAP-010 \| Prompt cache blocks \| Anthropic `system_blocks` with `cache_control: ephemeral` \| llm \| 001,020 \| SC-01,03 \| 011\| CAP-\| CAP-011 \| Provider factory \| Select adapter via config/env (`LLM_PROVIDER`, model tier) \| llm \| 001 \| all \| --- # Group B — Prompt (`prompt/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| 020\| CAP-\| CAP-020 \| Layered prompt stack \| Foundation + identity + recipe + dynamic context \| prompt \| — \| all \| 021\| CAP-\| CAP-021 \| PromptBuilder \| Fluent `with_identity().with_workflow().with_context().build()` \| prompt \| 020 \| all \| 022\| CAP-\| CAP-022 \| Workflow recipe layer \| Named template injects task guidance + expected tools \| prompt \| 020,021 \| SC-01,03 \| 023\| CAP-\| CAP-023 \| Validate-before-LLM \| Reject invalid inputs structurally before spending tokens \| prompt \| — \| SC-02,03 \| --- # Group C — Tools (`tools/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| 030\| CAP-\| CAP-030 \| Tool registry \| Map tool name → domain service callable \| tools \| — \| all \| 031\| CAP-\| CAP-031 \| Tool envelope \| Every call returns `{success, result, error}`; never raises to loop \| tools \| 030 \| all \| 032\| CAP-\| CAP-032 \| Write guard \| Allowlist/deny-by-default for mutating tools \| tools \| 030,031 \| SC-02,05 \| 033\| CAP-\| CAP-033 \| HITL destructive tools \| Park delete/mutate until human approval \| tools \| 031 \| SC-05 \| 034\| CAP-\| CAP-034 \| Schema adapter \| Reflect Python fn → Anthropic/OpenAI tool JSON schema \| tools \| 030 \| SC-01 \| 035\| CAP-\| CAP-035 \| Intra-plan read cache \| Cache read tool results by plan+tool+args hash \| tools \| 031 \| SC-01,03 \| \| CAP-036 \| Auth identity override \| Server injects/overrides `user_id` in every tool call \| tools \| 031 \| SC-05 \| CAP-036 \| --- # Group C2 — Context (`context/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| \| CAP-037 \| Context snapshot hydration \| Pre-compute user/domain state JSON for prompt layer 4 \| context \| — \| SC-01 \| CAP-037 \| \| CAP-038 \| Snapshot invalidation hooks \| Invalidate/rebuild snapshot on domain mutations \| context \| 037 \| SC-01 \| CAP-038 \| \| CAP-039 \| Dual tool exposure \| Conversation=writes only; workflow=full registry \| context \| 037,030 \| SC-01,03 \| CAP-039 \| --- # Group D — Agent loop (`loop/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| 040\| CAP-\| CAP-040 \| Bounded ReAct loop \| LLM↔tools iterate until `end_turn` or cap \| loop \| 001,002,031 \| SC-01,04 \| 041\| CAP-\| CAP-041 \| History window \| Sliding window on messages sent to LLM \| loop \| 040 \| SC-01 \| 042\| CAP-\| CAP-042 \| Context filter \| Filter history by `context_type`/`context_id` \| loop \| 041 \| SC-01 \| 043\| CAP-\| CAP-043 \| Force-final breakers \| Inject "answer now" when iteration/tool churn exceeded \| loop \| 040 \| SC-01 \| 044\| CAP-\| CAP-044 \| Plan handoff intercept \| `create_plan` success → enqueue worker → stop loop \| loop \| 040,050,062 \| SC-01 \| --- # Group E — Plan (`plan/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| 050\| CAP-\| CAP-050 \| Durable plan model \| Persist ordered steps with status/result/error \| plan \| — \| SC-01,03 \| 051\| CAP-\| CAP-051 \| Step state machine \| `pending→running→completed, failed, waiting_retry` \| plan \| 050 \| SC-01,03 \| 052\| CAP-\| CAP-052 \| Atomic mark_started \| `UPDATE … WHERE status IN (pending,waiting_retry)` \| plan \| 051 \| SC-01,03 \| 053\| CAP-\| CAP-053 \| Hybrid step flags \| `is_critical`, `is_planning`, `is_variable_assessment`, data-only \| plan \| 051 \| SC-03 \| 054\| CAP-\| CAP-054 \| Step synthesis chain \| Pass prior `llm_synthesis` to next LLM step \| plan \| 053 \| SC-03 \| 055\| CAP-\| CAP-055 \| Plan adapt \| Insert/remove/update pending steps mid-run \| plan \| 051 \| SC-01,03 \| --- # Group F — Worker (`worker/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| 060\| CAP-\| CAP-060 \| Async plan worker \| Celery task runs `execute_plan(plan_id)` loop \| worker \| 050,051 \| SC-01,03 \| 061\| CAP-\| CAP-061 \| Dual-layer 429 \| In-call backoff + job `waiting_retry` + Celery retry \| worker \| 005,060 \| SC-01,03 \| 062\| CAP-\| CAP-062 \| on_commit enqueue \| `transaction.on_commit(lambda: execute_plan.delay(id))` \| worker \| 060 \| SC-01,03 \| 063\| CAP-\| CAP-063 \| acks_late broker \| `acks_late=True`; `visibility_timeout` > max task duration \| worker \| 060 \| SC-01,03 \| 064\| CAP-\| CAP-064 \| Orphan recovery \| Periodic beat re-dispatches stuck plans \| worker \| 060,065 \| SC-01,03 \| 065\| CAP-\| CAP-065 \| Running reset \| Reset stale `running` → `pending` before re-queue \| worker \| 052 \| SC-01,03 \| 066\| CAP-\| CAP-066 \| Per-step model tier \| Planning=large model; data/assess=cheap model \| worker \| 001,011,060 \| SC-01,03 \| --- # Group G — Blackboard (`blackboard/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| 070\| CAP-\| CAP-070 \| Blackboard schema \| Fixed string keys: phase, hypothesis, current_plan, … \| blackboard \| — \| SC-01 \| 071\| CAP-\| CAP-071 \| Extract and truncate \| Parse model text → allowlisted dict ≤ N chars \| blackboard \| 070 \| SC-01 \| 072\| CAP-\| CAP-072 \| Retain on parse fail \| Bad extract keeps prior board \| blackboard \| 071 \| SC-01 \| 073\| CAP-\| CAP-073 \| Durability tier \| In-process vs JSON column on run/plan/conversation \| blackboard \| 070 \| SC-01 \| --- # Group H — Learning (`learning/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| 080\| CAP-\| CAP-080 \| Step outcome capture \| Persist assessment/satisfaction/suggestion on steps \| learning \| 051 \| optional \| 081\| CAP-\| CAP-081 \| Learned rules inject \| Append-only rules prepended to foundation prompt \| learning \| 020 \| optional \| --- # Group I — Knowledge & memory (`knowledge/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| \| CAP-090 \| Reference RAG retrieval \| Optional `search_knowledge` over document index (Tier 4) \| knowledge \| 030,031,094 \| optional \| CAP-090 \| \| CAP-091 \| Semantic context search \| NL query → ranked entities across large state (Tier 2) \| knowledge \| 030,031 \| SC-01 optional \| CAP-091 \| \| CAP-092 \| AI-managed profile memory \| Persistent preferences/patterns updated by agent (Tier 3) \| knowledge \| 030,031 \| optional \| CAP-092 \| \| CAP-093 \| Entity notes graph \| Topic/entity-linked notes for recurring subjects (Tier 5) \| knowledge \| 030,031 \| optional \| CAP-093 \| \| CAP-094 \| Reference knowledge library \| Ingest/version reference docs for RAG (Tier 4 store) \| knowledge \| — \| optional \| CAP-094 \| --- # Group J — Streaming (`streaming/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| 100\| CAP-\| CAP-100 \| SSE progress events \| Typed events: token, plan_step, rate_limit \| streaming \| 040 or 060 \| SC-01,03 \| --- # Group K — Events (`events/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| 110\| CAP-\| CAP-110 \| Event ingress \| Domain event → handler → short loop or enqueue plan \| events \| 120 \| SC-04 \| --- # Group M — Observability (`observability/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| \| CAP-101 \| Agent interaction trace \| correlation_id + per-LLM-call usage/latency/cost \| observability \| 001 \| all prod \| CAP-101 \| --- # Group L — Factory (`factory/`) \| ID \| Name \| Job \| Module \| Requires \| Scenarios \| Spec \| \|----\|------\|-----\|--------\|----------\|-----------\|------\| 120\| CAP-\| CAP-120 \| Agent factory \| Composition root wires LLM + tools + prompt + optional board \| factory \| 001,030,020 \| all \| 121\| CAP-\| CAP-121 \| Agent identities \| Frozen dataclass: tone, tools, model tier per persona \| factory \| 120 \| all \| 122\| CAP-\| CAP-122 \| Model tier config \| Named tiers: planning / execution / field + env mapping \| factory \| 011,121 \| SC-01,02,03 \| --- ## 4.2 Capability specifications Intro — each spec is a `# CAP-NNN` section below. --- # CAP-001 · LLM Port protocol Job: Single `complete()` entry point; all agents depend on protocol, never vendor SDK. Need when: Any in-app LLM call (all scenarios). Skip when: Never — if no LLM, skip entire agent architecture. Requires: — \| Pairs with: CAP-004, CAP-011 \| Module: `llm/` Contract - `BaseLLM.complete(messages, system, max_tokens, temperature) -> LLMResponse` - `LLMResponse`: `content`, `thinking`, `model`, `usage`, `stop_reason` - `LLMError` on timeout/API failure Code — protocol ```python from dataclasses import dataclass, field from typing import Protocol, runtime_checkable @dataclass class LLMMessage: role: str # system \| user \| assistant content: str @dataclass class LLMResponse: content: str model: str = "" usage: dict = field(default_factory=dict) stop_reason: str = "end_turn" thinking: str = "" @runtime_checkable class BaseLLM(Protocol): model_id: str def complete( self, messages: list[LLMMessage], system: str = "", max_tokens: int = 1024, temperature: float = 0.2, ) -> LLMResponse: ... class LLMError(Exception): ... ``` Wire: `factory/` selects adapter; `loop/`, `worker/`, field agents call `complete()` only. Test: `test_cap_001_adapter_satisfies_protocol` Fails if: Agent imports Anthropic/OpenAI SDK directly — cannot swap providers or test with CAP-004. --- # CAP-002 · Tool-calling generate Job: LLM returns structured `tool_calls` alongside assistant text for ReAct loops. Need when: SC-01, SC-03, SC-04 — any agent that invokes tools via the LLM protocol. Skip when: SC-02 field extract only (JSON in content body, no tool-calling protocol). Requires: CAP-001 \| Pairs with: CAP-034, CAP-040 \| Module: `llm/` Contract - `complete_with_tools(messages, system, tools, …) -> LLMResponse` extends CAP-001 - `LLMResponse.tool_calls: list[dict] \| None` — normalized at adapter boundary - Each call: `{id, name, arguments}` — arguments is a dict (never raw string) - `stop_reason`: `end_turn` when no tools; `tool_use` when tool_calls present - Adapters map Anthropic/OpenAI/Ollama shapes into this contract — loop never parses free text Code — protocol extension + adapter normalize ```python @dataclass class LLMResponse: content: str tool_calls: list[dict] \| None = None stop_reason: str = "end_turn" thinking: str = "" model: str = "" usage: dict \| None = None class BaseLLM(Protocol): def complete_with_tools( self, messages: list[LLMMessage], system: str, , tools: list[dict], max_tokens: int = 4096, temperature: float = 0.2, ) -> LLMResponse: ... def normalize_tool_calls(raw: dict) -> list[dict]: calls = [] for tc in raw.get("tool_calls") or raw.get("tool_use") or []: calls.append({ "id": tc.get("id", tc.get("call_id", "")), "name": tc["name"], "arguments": tc.get("input") or tc.get("arguments") or {}, }) return calls ``` Wire:* `loop/react.py` calls `complete_with_tools`; pass tool schemas from CAP-034. Field agents (SC-02) use `complete()` only. Test: `test_cap_002_tool_calls_round_trip` Fails if: Loop regex-parses tool calls from assistant text — brittle and breaks on provider change. --- # CAP-003 · Token stream Job: Stream partial tokens to caller for live UI rendering. Need when: SC-01 with live chat UI (pairs with CAP-100). Skip when: Batch/field agents with no streaming UI. Requires: CAP-001 \| Pairs with: CAP-100 \| Module: `llm/` Contract - `stream(messages, system) -> Iterator[str]` yields content deltas - Separate from progress events (plan steps) in CAP-100 Code — stream iterator ```python from collections.abc import Iterator class BaseLLM(Protocol): def stream( self, messages: list[LLMMessage], system: str = "", , max_tokens: int = 4096, ) -> Iterator[str]: ... ``` Wire:* UI/SSE publisher consumes `stream()`; do not mix plan progress into token stream. Test: `test_cap_003_stream_yields_deltas` Fails if: Blocking `complete()` only — chat UI freezes until full response. Status: sketch — implement when CAP-100 selected --- # CAP-004 · ScriptedLLM Job: Replay queued `LLMResponse` values in order — the only allowed LLM mock in integration tests. Need when: All scenarios for CI agent proofs (§7). Skip when: Production runtime — never deploy ScriptedLLM. Requires: CAP-001 \| Pairs with: — \| Module: `llm/` Contract - Constructor takes ordered response strings or `LLMResponse` objects - `complete()` pops next; raises `LLMError` when exhausted Code — test double ```python class ScriptedLLM: model_id = "scripted" def __init__(self, responses: list[str]) -> None: if not responses: raise ValueError("ScriptedLLM requires at least one response") self._responses = list(responses) self._index = 0 def complete(self, messages, system="", max_tokens=1024, temperature=0.2) -> LLMResponse: if self._index >= len(self._responses): raise LLMError(f"ScriptedLLM exhausted after {len(self._responses)} calls") content = self._responses[self._index] self._index += 1 return LLMResponse(content=content, model=self.model_id) ``` Wire: Inject via `factory.create_agent(..., llm=ScriptedLLM([...]))` in pytest only. Test: `test_cap_004_scripted_replays_in_order` Fails if: Mocking domain services or tools — hides real integration failures. --- # CAP-005 · LLM retry backoff Job: Exponential backoff wrapper for rate limits and transient LLM errors. Need when: SC-01, SC-03 — any production LLM calls that may 429. Skip when: Local-only dev with zero rate limits (still recommended). Requires: CAP-001 \| Pairs with: CAP-006, CAP-061 \| Module: `llm/` Contract - Retry capped (e.g. min(30 * 2(n-1), 120) seconds) - Re-raise after max attempts Code — retry helper** ```python import time from typing import Callable, TypeVar T = TypeVar("T") def with_llm_retry( fn: Callable[[], T], , max_attempts: int = 5, status_callback: Callable[[str, int, int], None] \| None = None, ) -> T: for attempt in range(1, max_attempts + 1): try: return fn() except RateLimitError as exc: if attempt == max_attempts: raise delay = min(30 (2 (attempt - 1)), 120) if status_callback: status_callback(str(exc), attempt, delay) time.sleep(delay) raise RuntimeError("unreachable") ``` Wire: Wrap adapter `complete()` calls in `loop/` and `worker/`; field agents use for long batch runs. Test: `test_cap_005_retries_on_rate_limit` Fails if: Uncaught 429 crashes agent mid-run with no resume path. --- # CAP-006 · Retry status callback Job: Notify caller during backoff so UI/logs show wait state without full SSE. Need when: SC-01 — user-visible chat during rate-limit waits. Skip when: Headless batch with no status surface. Requires: CAP-005 \| Pairs with: CAP-100 \| Module: `llm/` Contract - Signature: `(message: str, attempt: int, delay_seconds: int) -> None` - Called before each sleep in retry helper Code — callback usage ```python def on_rate_limit(message: str, attempt: int, delay: int) -> None: logger.info("rate_limit wait attempt=%s delay=%s msg=%s", attempt, delay, message) # optional: emit SSE rate_limit_status event (CAP-100) with_llm_retry(lambda: llm.complete(msgs), status_callback=on_rate_limit) ``` Wire: Pass callback from `loop/` or conversation service into LLM retry wrapper. Test: `test_cap_006_callback_fires_before_sleep` Fails if: Silent 120s sleeps — users think the app hung. --- # CAP-007 · Extended thinking request Job: Enable provider reasoning budget on planning-heavy LLM calls. Need when: SC-01/03 planning or narrative steps using Claude-style extended thinking. Skip when: SC-02 field JSON extract; cheap assessment/data steps. Requires: CAP-001 \| Pairs with: CAP-008 \| Module: `llm/` Contract - Optional param: `thinking={"type": "enabled", "budget_tokens": N}` - Default N illustrative: 8000 for planning tier Code — Anthropic-style request ```python response = client.messages.create( model=model, messages=messages, max_tokens=16000, thinking={"type": "enabled", "budget_tokens": 8000}, ) ``` Wire: Worker selects CAP-007 only for `is_planning=True` steps (CAP-053, CAP-066). Test: `test_cap_007_thinking_enabled_on_planning_step` Fails if: Thinking enabled on every call — cost/latency explosion on data steps. --- # CAP-008 · Thinking response normalize Job: Adapters return machine-parseable `content`; provider reasoning goes to `thinking`. Need when: SC-02; any step that parses JSON from LLM output; all thinking models (Qwen3, Claude, o-series). Skip when: Natural-language-only output, never parsed structurally. Requires: CAP-001 \| Pairs with: CAP-009 \| Module: `llm/` Contract - `LLMResponse.content` — answer only (tags stripped) - `LLMResponse.thinking` — optional trace; log at DEBUG only - Normalize in adapter `_parse_response`, not in agent/runner Code — adapter parse (Ollama example) ```python from llm.structured import normalize_llm_text def _parse_response(raw: dict) -> LLMResponse: message = raw.get("message") or {} thinking = str(message.get("thinking") or "") raw_content = str(message.get("content") or "") content = normalize_llm_text(raw_content) return LLMResponse(content=content, thinking=thinking, model=raw.get("model", "")) ``` Wire: Every provider adapter implements `_parse_response`; log content_chars/thinking_chars at INFO. Test: `test_cap_008_thinking_field_separated_from_content` Fails if: Parser sees `` or prose mixed with JSON → `None` → silent zero ops. --- # CAP-009 · Structured JSON extract Job: Shared strip + JSON parse for map/extract/metric steps. Need when:** SC-02; any `extract_json_` consumer. Skip when:* Tool-calling or NL-only responses. Requires: CAP-008 \| Pairs with: — \| Module: `llm/` Contract - `normalize_llm_text(raw) -> str` - `extract_json_array(raw) -> list[dict] \| None` - `extract_json_object(raw) -> dict \| None` - Bracket/brace slice fallback on parse fail Code — extractors ```python import json import re _THINKING_RE = re.compile(r"<\sthink(?:ing)?\s>[\s\S]?<\s/\sthink(?:ing)?\s>", re.I) def normalize_llm_text(raw: str) -> str: text = _THINKING_RE.sub("", raw or "").strip() return strip_markdown_fence(text) def extract_json_array(raw: str) -> list[dict] \| None: text = normalize_llm_text(raw) if not text: return None try: data = json.loads(text) except json.JSONDecodeError: start, end = text.find("["), text.rfind("]") if start < 0 or end <= start: return None data = json.loads(text[start : end + 1]) return [x for x in data if isinstance(x, dict)] if isinstance(data, list) else None ``` Wire: Single module imported by field agent and discovery runner — never duplicate parsers. Test: `test_cap_009_thinking_wrapped_json_array_parses` Fails if: Parse returns None but pipeline exits 0 with zero domain ops. --- # CAP-010 · Prompt cache blocks Job: Anthropic-style ephemeral cache on stable system prompt blocks. Need when: SC-01/03 with repeated LLM calls sharing foundation prompt. Skip when: Single-shot field extract (SC-02). Requires: CAP-001, CAP-020 \| Pairs with: CAP-021 \| Module: `llm/` Contract - `system_blocks: list[dict]` with `cache_control: {type: ephemeral}` on stable layers - Dynamic/user content never in cached blocks Code — system blocks ```python system_blocks = [ {"type": "text", "text": FOUNDATION_PROMPT, "cache_control": {"type": "ephemeral"}}, {"type": "text", "text": domain_rules, "cache_control": {"type": "ephemeral"}}, ] client.messages.create(model=model, system=system_blocks, messages=messages) ``` Wire: `PromptBuilder.build()` returns blocks for layers 1–2; layer 4 goes in user message. Test: `test_cap_010_cached_blocks_sent_on_second_call` Fails if: Full system prompt resent every call — cost/latency multiply. --- # CAP-011 · Provider factory Job: Select LLM adapter and model tier from config/env. Need when: All scenarios. Skip when: — Requires: CAP-001 \| Pairs with: CAP-122 \| Module: `llm/` Contract - `LLM_PROVIDER` env: anthropic \| openai \| ollama \| scripted - `build_llm(tier: str) -> BaseLLM` Code — factory ```python import os def build_llm(, tier: str = "field") -> BaseLLM: provider = os.getenv("LLM_PROVIDER", "ollama") if provider == "scripted": raise ValueError("use ScriptedLLM directly in tests") if provider == "ollama": from llm.adapters.ollama import OllamaClient model = os.getenv("LLM_OLLAMA_MODEL", "qwen3:14b") return OllamaClient(model=model) ... ``` Wire:* `factory.create_agent` calls `build_llm(identity.model_tier)`. Test: `test_cap_011_factory_returns_protocol_instance` Fails if: Hard-coded model in agent code — cannot route tiers (CAP-066). --- # CAP-020 · Layered prompt stack Job: Four layers: foundation, identity, recipe, dynamic. Need when: Scenarios: all. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: — \| Pairs with: CAP-021 \| Module: `prompt/` Contract - Layer 1 Foundation: tools protocol, safety, HITL - Layer 2 Identity: persona - Layer 3 Recipe (optional) - Layer 4 Dynamic: run context Code ```python FOUNDATION = """You must use tools for facts. Use create_plan for 2+ tool steps.""" ``` Wire: See Assembly templates templates; pairs with CAP-022. Test: `test_cap_020_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-021 · PromptBuilder Job: Fluent builder assembles layers into system prompt or blocks. Need when: Scenarios: all. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-020 \| Pairs with: CAP-010 \| Module: `prompt/` Contract - `with_identity()`, `with_workflow()`, `with_context()`, `build() -> str \| blocks` Code ```python class PromptBuilder: def with_identity(self, identity): ... def with_context(self, ctx): ... def build(self) -> str: ... ``` Wire: See Assembly templates templates; pairs with CAP-020. Test: `test_cap_021_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-022 · Workflow recipe layer Job: Named DB template injects task guidance between identity and dynamic. Need when: Scenarios: SC-01,03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-020,021 \| Pairs with: — \| Module: `prompt/` Contract - Template: name, prompt_template, required_tools, expected_steps Code ```python @dataclass class WorkflowTemplate: name: str prompt_template: str required_tools: list[str] ``` Wire: See Assembly templates templates; pairs with CAP-021. Test: `test_cap_022_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-023 · Validate-before-LLM Job: Structural validation rejects bad inputs before token spend. Need when: Scenarios: SC-02,03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: — \| Pairs with: — \| Module: `prompt/` Contract - Validate snapshot/schema/metamodel constraints pre-call Code ```python def validate_extract_input(snapshot: dict) -> None: if not snapshot.get("files"): raise ValueError("empty snapshot") ``` Wire: See Assembly templates templates. Test: `test_cap_023_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-030 · Tool registry Job: Map tool name → callable over domain services. Need when: Scenarios: all with tools. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: — \| Pairs with: CAP-031 \| Module: `tools/` Contract - `registry: dict[str, Callable]` built at factory time Code ```python REGISTRY: dict[str, Callable] = {} def register(name: str): def deco(fn): REGISTRY[name] = fn; return fn return deco ``` Wire: See Assembly templates templates; pairs with CAP-031. Test: `test_cap_030_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-031 · Tool envelope Job: Stable `{success, result, error}`; never raise to loop. Need when: Scenarios: all with tools. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-030 \| Pairs with: CAP-040 \| Module: `tools/` Contract - Executor catches exceptions; returns envelope Code ```python def execute(self, tool_call: dict) -> dict: try: fn = self.registry[tool_call["name"]] return {"success": True, "result": fn(tool_call["arguments"]), "error": None} except Exception as exc: return {"success": False, "result": None, "error": str(exc)} ``` Wire: See Assembly templates templates; pairs with CAP-030. Test: `test_cap_031_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-032 · Write guard Job: Allowlist or deny-by-default for mutating tools. Need when: Scenarios: SC-02,05. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-030,031 \| Pairs with: CAP-033 \| Module: `tools/` Contract - `WRITE_TOOLS` frozenset or explicit deny list Code ```python WRITE_TOOLS = frozenset({"propose_changeset", "delete_element"}) def is_write(tool_name: str) -> bool: return tool_name in WRITE_TOOLS ``` Wire: See Assembly templates templates; pairs with CAP-031. Test: `test_cap_032_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-033 · HITL destructive tools Job: Park destructive tool calls as suggested actions pending approval. Need when: Scenarios: SC-05. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-031 \| Pairs with: CAP-036 \| Module: `tools/` Contract - Destructive tools return pending approval record, not immediate execute Code ```python if is_write(tool_call["name"]): return {"success": True, "result": {"status": "pending_approval", "tool": tool_call}, "error": None} ``` Wire: See Assembly templates templates; pairs with CAP-031. Test: `test_cap_033_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-034 · Schema adapter Job: Reflect Python callables to provider tool JSON schemas. Need when: Scenarios: SC-01. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-030 \| Pairs with: — \| Module: `tools/` Contract - Docstring → description; type hints → input_schema Code ```python def to_anthropic_tool(fn: Callable) -> dict: return {"name": fn.__name__, "description": fn.__doc__.split("\n")[0], "input_schema": hints_to_schema(fn)} ``` Wire: See Assembly templates templates; pairs with CAP-030. Test: `test_cap_034_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-035 · Intra-plan read cache Job: Cache read-tool results keyed by plan+tool+args hash. Need when: Scenarios: SC-01,03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-031 \| Pairs with: — \| Module: `tools/` Contract - Key: `plan_id:tool:sha256(args)`; invalidate on plan terminal Code ```python def cache_key(plan_id: int, tool: str, args: dict) -> str: import hashlib, json h = hashlib.sha256(json.dumps(args, sort_keys=True).encode()).hexdigest() return f"{plan_id}:{tool}:{h}" ``` Wire: See Assembly templates templates; pairs with CAP-031. Test: `test_cap_035_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-036 · Auth identity override Job: Hard-inject server `user_id`; override model-supplied values in tool args. Need when: Scenarios: SC-05. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-031 \| Pairs with: CAP-033 \| Module: `tools/` Contract - Override before every tool execute; prompt states never trust user-supplied user_id Code ```python def execute(self, tool_call: dict, , auth_user_id: int) -> dict: args = {tool_call.get("arguments", {}), "user_id": auth_user_id} ... ``` Wire:* See Assembly templates templates; pairs with CAP-031. Test: `test_cap_036_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-037 · Context snapshot hydration Job: Pre-compute structured user/domain state as JSON for prompt layer 4 (dynamic context). Need when: SC-01 with dual execution path; domain state too large or too chatty to fetch via read tools each turn. Skip when: SC-02 batch (single-shot input); SC-03 data steps pull sources directly; tiny domain where read tools in chat are acceptable without CAP-039. Requires: — \| Pairs with: CAP-038, CAP-039, CAP-010 \| Module: `context/` Contract - `get_or_build(scope_id) -> dict` returns `{snapshot, version, generated_at}` - Snapshot is structured JSON — intents, tasks, recent activity — not raw ORM dumps - Inject into `PromptBuilder.with_context(snapshot=...)` (layer 4); never duplicate full snapshot in cached layers 1–3 - Typical TTL: 1–5 minutes in process cache or Redis; authoritative store optional Code — snapshot service ```python from django.core.cache import cache class SnapshotService: TTL_SECONDS = 300 def get_or_build(self, scope_id: str) -> dict: key = f"agent_snapshot:{scope_id}" cached = cache.get(key) if cached: return cached snapshot = self._build_from_domain(scope_id) payload = { "snapshot": snapshot, "version": self._next_version(scope_id), "generated_at": timezone.now().isoformat(), } cache.set(key, payload, self.TTL_SECONDS) return payload def _build_from_domain(self, scope_id: str) -> dict: ... # aggregate via domain services — not LLM ``` Wire: Chat handler calls `get_or_build` before `bounded_react_loop`; worker may bypass snapshot and use read tools (CAP-039). Test: `test_cap_037_snapshot_injected_into_prompt` Fails if: Chat loop calls dozens of read tools per message while CAP-037 selected — dual path not wired. --- # CAP-038 · Snapshot invalidation hooks Job: Invalidate or bump snapshot version when domain mutations occur so chat never reads stale layer-4 context. Need when: CAP-037 in use; any write tool or background job mutates entities in the snapshot. Skip when: Snapshot is immutable for the session (read-only copilot). Requires: CAP-037 \| Pairs with: CAP-039 \| Module: `context/` Contract - Domain mutation (signal, service post-commit, or write-tool success) → `invalidate(scope_id)` or `bump_version(scope_id)` - Invalidation is cheap (delete cache key); rebuild is lazy on next `get_or_build` - Write tools MUST trigger invalidation after successful commit Code — invalidation hook ```python def invalidate(self, scope_id: str) -> None: cache.delete(f"agent_snapshot:{scope_id}") @receiver(post_save, sender=DomainEntity) def on_entity_changed(sender, instance, kwargs): SnapshotService().invalidate(instance.scope_id) ``` Wire: Register hooks for every entity type included in CAP-037 snapshot; call from write-tool executor on success. Test: `test_cap_038_mutation_bumps_snapshot_version` Fails if: User completes a write in chat but next message still sees pre-mutation snapshot. --- # CAP-039 · Dual tool exposure Job: Same tool registry; orchestrator exposes different subsets by execution mode. Need when: CAP-037 hydrates reads in chat — expose mutation-only tools in conversation; full registry in plan worker. Skip when: All tools are reads, or chat latency/cost of read tools is acceptable without snapshot. Requires: CAP-030, CAP-031, CAP-037 \| Pairs with: CAP-044, CAP-060 \| Module: `context/` Contract - Modes: `conversation` \| `workflow` - `conversation`: `WRITE_TOOLS` allowlist only (create/update/complete — project-defined) - `workflow`: full registry (reads, analyze, list, mutate) - MCP server may register all tools; factory passes mode into `ToolExecutor` - Attempt to call non-exposed tool → `{success: false, error: "tool not exposed in conversation mode"}` Code — mode-aware executor** ```python class ToolExecutor: def __init__(self, registry: dict, , mode: str = "conversation"): self.registry = registry self.mode = mode self.write_tools = frozenset(registry.keys()) & WRITE_TOOLS def exposed_names(self) -> frozenset[str]: if self.mode == "workflow": return frozenset(self.registry.keys()) return self.write_tools def execute(self, tool_call: dict) -> dict: name = tool_call["name"] if name not in self.exposed_names(): return {"success": False, "result": None, "error": f"tool {name!r} not exposed in {self.mode} mode"} ... ``` Wire:* `PlannerAgent` / CAP-040 uses `mode=conversation`; `execute_plan` worker uses `mode=workflow`. Test: `test_cap_039_conversation_blocks_read_tool` Fails if: Chat agent still fan-outs read tools while CAP-037 snapshot is present — cost/latency unchanged. --- # CAP-091 · Semantic context search Job: Natural-language query → ranked subset of entities from large domain state (Tier 2 memory). Need when: Snapshot alone exceeds token budget; user asks "find logs about X" or "objectives due this week". Skip when: Tier-1 snapshot fits comfortably; SC-02 batch with fixed input. Requires: CAP-030, CAP-031 \| Pairs with: CAP-037, CAP-090 \| Module: `knowledge/` Contract - Single tool: `semantic_context_search(scope_id, query, entity_types?, limit?) -> {results, metadata}` - Embedding similarity or indexed search over entity text fields - Returns snippets + relevance scores — not full snapshot - LLM may call instead of assuming full state is in layer 4 Code — search tool ```python def semantic_context_search( scope_id: str, query: str, , entity_types: list[str] \| None = None, limit: int = 20, ) -> dict: embedding = embed(query) hits = index.search(scope_id, embedding, types=entity_types, limit=limit) return {"query": query, "results": hits, "metadata": {"count": len(hits)}} ``` Wire:* Register in workflow mode always; in conversation mode only if snapshot alone is insufficient (optional read). Test: `test_cap_091_semantic_search_returns_ranked_hits` Fails if: Entire history embedded in every prompt instead of query-time retrieval. --- # CAP-092 · AI-managed profile memory Job: Persistent, agent-updatable user profile (preferences, patterns, strengths, constraints) — Tier 3. Need when: Personalization across sessions; agent should remember stable facts without re-deriving from logs. Skip when: Anonymous or ephemeral agents; profile owned by explicit user settings UI only. Requires: CAP-030, CAP-031 \| Pairs with: CAP-037 \| Module: `knowledge/` Contract - Store: structured JSON profile per user with version + `updated_by` (agent \| user) - Tool: `update_user_profile(scope_id, patch, rationale)` — merge patch; audit changes - Inject summary slice into layer 4 (not full history) - Human review recommended for sensitive fields (optional gate) Code — profile patch ```python def update_user_profile(scope_id: str, patch: dict, , rationale: str) -> dict: profile = Profile.objects.select_for_update().get(scope_id=scope_id) profile.data = deep_merge(profile.data, patch) profile.version += 1 profile.save() AuditLog.record(scope_id, patch, rationale) return profile.data ``` Wire:* Expose update tool in workflow or governed conversation writes; inject `profile_summary` in PromptBuilder. Test: `test_cap_092_profile_patch_persists` Fails if: Agent re-encodes same preferences in every conversation from scratch. --- # CAP-093 · Entity notes graph Job: Free-form notes attached to recurring entities (people, projects, topics) — Tier 5. Need when: User works with repeating entities; context is relational not flat. Skip when: Domain has no entity graph or notes are stored only in primary records. Requires: CAP-030, CAP-031 \| Pairs with: CAP-091 \| Module: `knowledge/` Contract - Tools: `get_entity_notes(entity_type, entity_id)`, `upsert_entity_note(...)`, optional `link_entities` - Notes are user/agent authored text + tags; searchable via CAP-091 - Inject relevant notes into layer 4 when `context_type`/`context_id` matches Code — note upsert ```python def upsert_entity_note( scope_id: str, entity_type: str, entity_id: str, body: str, , tags: list[str] \| None = None, ) -> dict: note, _ = EntityNote.objects.update_or_create( scope_id=scope_id, entity_type=entity_type, entity_id=entity_id, defaults={"body": body, "tags": tags or []}, ) return {"id": note.pk, "entity_type": entity_type, "entity_id": entity_id} ``` Wire:* Domain-specific entity types; index note text for CAP-091. Test: `test_cap_093_note_retrieved_for_active_context` Fails if: Same entity context re-explained every session with no note retention. --- # CAP-094 · Reference knowledge library Job: Ingest, version, and store reference documents (books, playbooks, frameworks) for RAG — Tier 4 store. Need when: Agent should cite or apply user-provided reference material on demand. Skip when: All guidance lives in foundation prompt / skills only. Requires: — \| Pairs with: CAP-090 \| Module: `knowledge/` Contract - Ingest pipeline: upload → chunk → embed → index (async job acceptable) - Metadata: `doc_type`, `title`, `version`, `tags` - CAP-090 `search_knowledge` queries this index — do not duplicate indexes Code — ingest stub ```python def ingest_reference_document( scope_id: str, title: str, content: str, , doc_type: str = "playbook", ) -> dict: doc = ReferenceDocument.objects.create(scope_id=scope_id, title=title, doc_type=doc_type) chunks = chunk_text(content) index.upsert(doc.id, chunks) return {"document_id": doc.id, "chunks": len(chunks)} ``` Wire:* Admin or API upload; CAP-090 registered when Tier 4 enabled. Test: `test_cap_094_ingest_then_search_knowledge_hit` Fails if: CAP-090 searches ad-hoc files with no versioned library backing. --- # CAP-101 · Agent interaction trace Job: End-to-end traceability: correlation_id from API entry through LLM calls; normalized usage, latency, cost per interaction. Need when: Any production agent (all scenarios); required for support, cost control, debugging. Skip when: Local dev only with DEBUG logging (still recommended). Requires: CAP-001 \| Pairs with: CAP-006, CAP-100 \| Module: `observability/` Contract - Provider-agnostic at orchestrator boundary — adapters map vendor usage fields into `LLMResponse.usage` - `correlation_id`: propagated from HTTP header or generated at API entry; attached to logs, worker tasks, SSE events - `AgentInteraction` record per LLM call: `{correlation_id, conversation_id, plan_id?, model, input_tokens, output_tokens, latency_ms, estimated_cost}` - Cost = `tokens × rate_table(model_id)` — rates in config, not hard-coded in agents - Tool executions log `{correlation_id, tool_name, success, duration_ms}` separately from LLM cost Code — trace wrapper ```python @dataclass class AgentInteraction: correlation_id: str model: str input_tokens: int output_tokens: int latency_ms: int estimated_cost: Decimal def traced_complete(llm: BaseLLM, , correlation_id: str, kwargs) -> LLMResponse: started = time.monotonic() resp = llm.complete(kwargs) latency_ms = int((time.monotonic() - started) 1000) AgentInteraction.objects.create( correlation_id=correlation_id, model=resp.model, input_tokens=resp.usage.get("input_tokens", 0), output_tokens=resp.usage.get("output_tokens", 0), latency_ms=latency_ms, estimated_cost=estimate_cost(resp.model, resp.usage), ) logger.info("llm_complete correlation_id=%s model=%s latency_ms=%s", correlation_id, resp.model, latency_ms) return resp ``` Wire: Middleware sets `correlation_id`; pass through loop, worker, SSE publisher; never rely on provider-specific log formats in agent code. Test: `test_cap_101_correlation_id_links_api_to_interaction_row` Fails if: Support asks for a failure timestamp and only provider dashboard exists — no request-level trace. --- # CAP-040 · Bounded ReAct loop Job: LLM↔tools iterate until `end_turn` or iteration cap; optional plan handoff callback. Need when: SC-01, SC-04 — conversational or event-triggered tool-calling agents. Skip when: SC-02 batch extract; SC-03 compiled pipeline worker (uses CAP-060 step loop instead). Requires: CAP-001, CAP-002, CAP-031 \| Pairs with: CAP-043, CAP-044 \| Module: `loop/` Contract - Hard cap on iterations (default 10) and optional tool-call count - Each round: `complete_with_tools` → if no `tool_calls`, return assistant text - Append `{role: tool, tool_call_id, content}` messages for each executed tool - Tool results come from CAP-031 envelope — never raise into loop - Optional `on_plan_created(plan_id) -> str` hook for CAP-044 intercept - When cap exceeded, delegate to CAP-043 force-final (if selected) Code — bounded loop ```python from dataclasses import dataclass from typing import Callable @dataclass class ToolCall: id: str name: str arguments: dict def bounded_react_loop( llm, executor, messages: list, system: str, , tool_schemas: list[dict], max_iter: int = 10, on_plan_created: Callable[[int], str] \| None = None, ) -> str: for _ in range(max_iter): resp = llm.complete_with_tools(messages, system, tools=tool_schemas) if not resp.tool_calls: return resp.content or "" for tc in resp.tool_calls: if tc["name"] == "create_plan" and on_plan_created: result = executor.execute(tc) if result.get("success") and result.get("result", {}).get("plan_id"): return on_plan_created(result["result"]["plan_id"]) envelope = executor.execute(tc) messages.append({ "role": "tool", "tool_call_id": tc.get("id", tc["name"]), "content": envelope.get("result") if envelope.get("success") else envelope.get("error", ""), }) return force_final_answer(llm, messages, system, tool_schemas=tool_schemas) ``` Wire:* Factory passes `tool_schemas` from CAP-034; wire `on_plan_created` when CAP-044 selected. Wrap `llm` with CAP-101 trace wrapper in production. Test: `test_cap_040_tool_round_trip_and_cap` Fails if: Loop calls `complete()` without tools while agent scenario requires tool use — SC-01 cannot function. --- # CAP-041 · History window Job: Sliding window truncates messages sent to LLM. Need when: Scenarios: SC-01. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-040 \| Pairs with: CAP-042 \| Module: `loop/` Contract - Keep last N messages after filtering Code ```python def window_messages(msgs: list, , limit: int = 20) -> list: return msgs[-limit:] ``` Wire:* See Assembly templates templates; pairs with CAP-040. Test: `test_cap_041_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-042 · Context filter Job: Filter history by context_type/context_id before windowing. Need when: Scenarios: SC-01. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-041 \| Pairs with: — \| Module: `loop/` Contract - Prevent cross-conversation bleed Code ```python def filter_context(msgs, , context_type: str, context_id: str) -> list: return [m for m in msgs if getattr(m, "context_type", None) == context_type and getattr(m, "context_id", None) == context_id] ``` Wire:* See Assembly templates templates; pairs with CAP-041. Test: `test_cap_042_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-043 · Force-final breakers Job: Inject no-tools final call when iteration/tool churn exceeded. Need when: Scenarios: SC-01. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-040 \| Pairs with: — \| Module: `loop/` Contract - Triggers: iter≥N, tools≥M, after create_plan, hard max Code ```python if iteration >= MAX or only_hitl_tools_remain: return llm.complete(messages + [{"role":"user","content":"Provide final answer now."}], system) ``` Wire: See Assembly templates templates; pairs with CAP-040. Test: `test_cap_043_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-044 · Plan handoff intercept Job: On successful `create_plan` tool call: persist plan, enqueue worker on commit, stop ReAct loop with user ack. Need when: SC-01 — chat hands durable work to background worker (CAP-060). Skip when: All work completes synchronously in the chat loop; SC-03-only pipelines enqueue without chat loop. Requires: CAP-040, CAP-050, CAP-062 \| Pairs with: CAP-100 \| Module: `loop/` Contract - Intercept inside CAP-040 when tool name is `create_plan` and envelope reports success + `plan_id` - Call CAP-062 enqueue (`on_commit`) before returning to user - Return brief summary string — do not continue iterating in the sync loop - Worker runs with CAP-039 `mode=workflow` (full tool registry) Code — handoff hook ```python def make_plan_handoff(, conversation_id: str, enqueue_fn) -> callable: def on_plan_created(plan_id: int) -> str: enqueue_fn(plan_id) # CAP-062: transaction.on_commit(lambda: execute_plan.delay(plan_id)) return f"Plan #{plan_id} queued — you'll see progress as steps complete." return on_plan_created # In PlannerAgent.handle_message: bounded_react_loop( self.llm, self.tools, messages=messages, system=system, tool_schemas=self.tool_schemas, on_plan_created=make_plan_handoff(conversation_id=conv_id, enqueue_fn=self._enqueue_plan), ) ``` Wire:* Pass hook from conversation service into CAP-040; publish CAP-100 `plan_created` SSE after enqueue. Test: `test_cap_044_handoff_stops_loop_and_enqueues` Fails if: Loop continues after create_plan — user waits on HTTP timeout while worker runs. --- # CAP-050 · Durable plan model Job: Persist `ExecutionPlan` + ordered `PlanStep` rows that survive process crash and worker retry. Need when: SC-01, SC-03 — any async multi-step agent work. Skip when: Single-shot sync chat with no background execution. Requires: — \| Pairs with: CAP-051, CAP-062 \| Module: `plan/` Contract - `ExecutionPlan`: `{id, status, context_json, created_at, conversation_id?}` - `PlanStep`: `{plan_id, order, action, tool_name?, args_json, status, result_json, error, llm_synthesis?}` - Plan statuses: `pending`, `running`, `completed`, `failed` - Steps ordered by `order` field; worker advances sequentially unless CAP-055 adapt - `from_template(template_id, context)` factory for SC-03 compiled pipelines Code — models (reference impl) ```python class ExecutionPlan(models.Model): PENDING, RUNNING, COMPLETED, FAILED = "pending", "running", "completed", "failed" status = models.CharField(max_length=20, default=PENDING) context_json = models.JSONField(default=dict) conversation_id = models.CharField(max_length=64, blank=True) def steps(self): return self.planstep_set.order_by("order") @classmethod def from_template(cls, template_id: str, context: dict) -> "ExecutionPlan": spec = PLAN_TEMPLATES[template_id] # product-defined step graph plan = cls.objects.create(status=cls.PENDING, context_json=context) for i, step in enumerate(spec["steps"]): PlanStep.objects.create(plan=plan, order=i, step) return plan class PlanStep(models.Model): plan = models.ForeignKey(ExecutionPlan, on_delete=models.CASCADE) order = models.PositiveIntegerField() action = models.CharField(max_length=128) tool_name = models.CharField(max_length=64, blank=True) args_json = models.JSONField(default=dict) status = models.CharField(max_length=20, default="pending") result_json = models.JSONField(null=True, blank=True) error = models.TextField(blank=True) llm_synthesis = models.TextField(blank=True) ``` Wire: Created by CAP-044 `create_plan` tool or SC-03 `enqueue_compiled_plan`; consumed by CAP-060 worker. Test: `test_cap_050_plan_persists_ordered_steps` Fails if: Plan state lives only in memory — crash loses in-flight agent work. --- # CAP-051 · Step state machine Job: Enforce `pending → running → completed\|failed\|waiting_retry` transitions; completed steps never re-run. Need when: SC-01, SC-03 — any CAP-050 durable plan executed by CAP-060. Skip when: No durable plan model selected. Requires: CAP-050 \| Pairs with: CAP-052, CAP-061 \| Module: `plan/` Contract - Valid transitions only; terminal states (`completed`, `failed`) are immutable - `waiting_retry` re-enters from CAP-061 429 handling - `next_pending()` returns lowest-order step with status `pending` or `waiting_retry` - Worker skips `completed` steps on resume — idempotent retry semantics Code — state helpers** ```python STEP_PENDING = "pending" STEP_RUNNING = "running" STEP_COMPLETED = "completed" STEP_FAILED = "failed" STEP_WAITING = "waiting_retry" TERMINAL = frozenset({STEP_COMPLETED, STEP_FAILED}) class PlanStep(models.Model): # ... fields from CAP-050 ... def mark_running(self) -> bool: if self.status in TERMINAL: return False self.status = STEP_RUNNING self.save(update_fields=["status"]) return True def mark_completed(self, result: dict, , synthesis: str = "") -> None: self.status = STEP_COMPLETED self.result_json = result self.llm_synthesis = synthesis self.save(update_fields=["status", "result_json", "llm_synthesis"]) def mark_waiting_retry(self, error: str) -> None: self.status = STEP_WAITING self.error = error self.save(update_fields=["status", "error"]) class ExecutionPlan(models.Model): def next_pending(self) -> PlanStep \| None: return self.steps().filter(status__in=[STEP_PENDING, STEP_WAITING]).first() ``` Wire:* CAP-060 worker loop calls `next_pending()` → execute → `mark_completed` / `mark_failed` / `mark_waiting_retry`. Test: `test_cap_051_completed_step_not_rerun_on_retry` Fails if: Worker re-executes completed steps after 429 retry — duplicate side effects. --- # CAP-052 · Atomic mark_started Job: Single worker owns plan via conditional UPDATE. Need when: Scenarios: SC-01,03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-051 \| Pairs with: CAP-065 \| Module: `plan/` Contract - `UPDATE plan SET status=running WHERE id=? AND status IN (pending,waiting_retry)` Code ```python def mark_started(plan_id: int) -> bool: updated = Plan.objects.filter(id=plan_id, status__in=["pending","waiting_retry"]).update(status="running") return updated == 1 ``` Wire: See Assembly templates templates; pairs with CAP-060. Test: `test_cap_052_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-053 · Hybrid step flags Job: Data / assessment / planning step semantics via booleans. Need when: Scenarios: SC-03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-051 \| Pairs with: CAP-054,066 \| Module: `plan/` Contract - `is_critical`, `is_planning`, `is_variable_assessment` Code ```python @dataclass class PlanStep: is_critical: bool = True is_planning: bool = False is_variable_assessment: bool = False ``` Wire: See Assembly templates templates; pairs with CAP-060. Test: `test_cap_053_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-054 · Step synthesis chain Job: Prior LLM step outputs passed as context to subsequent LLM steps. Need when: Scenarios: SC-03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-053 \| Pairs with: — \| Module: `plan/` Contract - Store `result["llm_synthesis"]`; inject formatted chain before next LLM step Code ```python def prior_syntheses(plan, before_order: int) -> str: parts = [s.result["llm_synthesis"] for s in plan.steps if s.order < before_order and s.result] return "\n".join(parts) ``` Wire: See Assembly templates templates; pairs with CAP-060. Test: `test_cap_054_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-055 · Plan adapt Job: Insert/remove/update pending steps when mission allows. Need when: Scenarios: SC-01,03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-051 \| Pairs with: — \| Module: `plan/` Contract - Only mutate pending steps; never completed Code ```python def insert_step(plan, after_order: int, step: PlanStep) -> None: assert step.status == "pending" ... ``` Wire: See Assembly templates templates; pairs with CAP-051. Test: `test_cap_055_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-060 · Async plan worker Job: Background task loops pending plan steps via `execute_single_step` outside the HTTP request thread. Need when: SC-01, SC-03 — durable work that outlives the sync chat or trigger request. Skip when: All agent work completes synchronously in CAP-040 with no plan model. Requires: CAP-050, CAP-051 \| Pairs with: CAP-061, CAP-062, CAP-066 \| Module: `worker/` Contract - Entry: `execute_plan(plan_id)` — shared task or equivalent broker job - CAP-052 `mark_started` on plan — only one worker owns a plan at a time - Loop: while `step := plan.next_pending()`: `execute_single_step(plan, step)` - `execute_single_step` uses CAP-039 `mode=workflow` (full tools); hybrid LLM steps use CAP-053/054/066 - On unhandled failure: mark plan `failed`, emit CAP-100 `plan_failed` - Never run steps as dumb action-string scripts without LLM when hybrid flags set (see Pattern 4 anti-patterns) Code — worker task (reference impl) ```python @shared_task(bind=True, acks_late=True) def execute_plan(self, plan_id: int) -> None: plan = ExecutionPlan.objects.select_for_update().get(id=plan_id) if not plan.mark_started(): # CAP-052 return tools = ToolExecutor(registry=build_tool_registry(), mode="workflow") # CAP-039 try: while step := plan.next_pending(): execute_single_step(plan, step, tools=tools, llm=build_llm_for_step(step)) plan.status = ExecutionPlan.COMPLETED plan.save(update_fields=["status"]) except RateLimitError as exc: raise self.retry(exc=exc, countdown=60) # CAP-061 except Exception as exc: plan.status = ExecutionPlan.FAILED plan.save(update_fields=["status"]) publish_plan_failed(plan.id, str(exc)) # CAP-100 raise ``` Wire: Enqueued via CAP-062 from CAP-044 or SC-03 trigger; pass `correlation_id` from originating request into task context for CAP-101. Test: `test_cap_060_worker_completes_all_steps` Fails if: Worker invoked synchronously inside HTTP handler — request times out on long plans. --- # CAP-061 · Dual-layer 429 Job: In-call backoff (CAP-005) plus job-level waiting_retry. Need when: Scenarios: SC-01,03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-005,060 \| Pairs with: — \| Module: `worker/` Contract - On 429 in worker: mark step waiting_retry; Celery retry with countdown Code ```python except RateLimitError as exc: step.mark_waiting_retry(str(exc)) raise self.retry(countdown=60) ``` Wire: See Assembly templates templates; pairs with CAP-005. Test: `test_cap_061_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-062 · on_commit enqueue Job: Enqueue background worker only after the DB transaction that created the plan commits successfully. Need when: SC-01, SC-03 — any CAP-044 handoff or compiled pipeline enqueue. Skip when: Plan rows are created outside a transaction (single autocommit statement) — still prefer explicit commit boundary. Requires: CAP-060 \| Pairs with: CAP-044 \| Module: `worker/` Contract - Never call `execute_plan.delay(plan_id)` inside an uncommitted transaction - Worker must see committed `ExecutionPlan` + `PlanStep` rows on first read - Use framework post-commit hook: Django `transaction.on_commit`, SQLAlchemy `after_commit`, etc. Code — enqueue helper ```python from django.db import transaction def enqueue_plan_after_commit(plan_id: int) -> None: transaction.on_commit(lambda: execute_plan.delay(plan_id)) # CAP-044 handoff: def on_plan_created(plan_id: int) -> str: enqueue_plan_after_commit(plan_id) return f"Plan #{plan_id} queued." # SC-03 compiled pipeline: def enqueue_compiled_plan(template_id: str, context: dict) -> int: plan = ExecutionPlan.from_template(template_id, context) plan.save() enqueue_plan_after_commit(plan.id) return plan.id ``` Wire: All plan creation paths (chat handoff, event handler, CI trigger) call this helper — never raw `.delay()` adjacent to uncommitted ORM writes. Test: `test_cap_062_worker_sees_committed_plan_rows` Fails if: Worker starts before commit — `DoesNotExist` or partial step set race. --- # CAP-063 · acks_late broker Job: Defer ACK until task completes; long visibility_timeout. Need when: Scenarios: SC-01,03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-060 \| Pairs with: — \| Module: `worker/` Contract - `acks_late=True`; broker visibility > worst-case task duration Code ```python # celery settings CELERY_TASK_ACKS_LATE = True CELERY_BROKER_TRANSPORT_OPTIONS = {"visibility_timeout": 7200} ``` Wire: See Assembly templates templates; pairs with CAP-060. Test: `test_cap_063_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-064 · Orphan recovery Job: Beat task re-dispatches plans stuck too long. Need when: Scenarios: SC-01,03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-060,065 \| Pairs with: — \| Module: `worker/` Contract - Find plans running/pending older than threshold; re-queue Code ```python def recover_orphaned_plans(): stale = Plan.objects.filter(status="running", updated_at__lt=threshold()) stale.update(status="pending") for p in stale: execute_plan.delay(p.id) ``` Wire: See Assembly templates templates; pairs with CAP-065. Test: `test_cap_064_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-065 · Running reset Job: Reset stale running→pending before re-dispatch. Need when: Scenarios: SC-01,03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-052 \| Pairs with: CAP-064 \| Module: `worker/` Contract - Required before mark_started succeeds on retry Code ```python Plan.objects.filter(status="running", updated_at__lt=cutoff).update(status="pending") ``` Wire: See Assembly templates templates; pairs with CAP-064. Test: `test_cap_065_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-066 · Per-step model tier Job: Planning steps use large model; data/assess use cheap model. Need when: Scenarios: SC-01,03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-001,011,060 \| Pairs with: CAP-007,053 \| Module: `worker/` Contract - Store `model_used` on step for audit Code ```python def llm_for_step(step) -> BaseLLM: if step.is_planning: return build_llm(tier="planning") return build_llm(tier="execution") ``` Wire: See Assembly templates templates; pairs with CAP-011. Test: `test_cap_066_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-070 · Blackboard schema Job: Fixed string keys for soft intent across turns. Need when: Scenarios: SC-01. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: — \| Pairs with: CAP-071 \| Module: `blackboard/` Contract - Keys: phase, hypothesis, current_plan, last_actions, next_intent Code ```python ALLOWED_KEYS = frozenset({"phase","hypothesis","current_plan","last_actions","next_intent"}) ``` Wire: See Assembly templates templates; pairs with CAP-071. Test: `test_cap_070_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-071 · Extract and truncate Job: Parse model text to allowlisted board dict ≤ max chars. Need when: Scenarios: SC-01. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-070 \| Pairs with: CAP-072 \| Module: `blackboard/` Contract - Drop unknown keys; enforce size cap (~500 chars) Code ```python def extract_blackboard(text: str, max_chars: int = 500) -> dict[str, str] \| None: data = parse_json_or_kv(text) if not data: return None board = {k: str(v) for k, v in data.items() if k in ALLOWED_KEYS} return truncate(board, max_chars) ``` Wire: See Assembly templates templates; pairs with CAP-070. Test: `test_cap_071_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-072 · Retain on parse fail Job: Invalid extract leaves prior board unchanged. Need when: Scenarios: SC-01. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-071 \| Pairs with: — \| Module: `blackboard/` Contract - `set_from_model_text() -> bool`; False means retain Code ```python def set_from_model_text(self, text: str) -> bool: board = extract_blackboard(text) if board is None: return False self._board = board return True ``` Wire: See Assembly templates templates; pairs with CAP-040. Test: `test_cap_072_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-073 · Durability tier Job: In-process vs JSON column on run/plan/conversation. Need when: Scenarios: SC-01. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-070 \| Pairs with: — \| Module: `blackboard/` Contract - Tier A: instance field; Tier B: persisted JSON Code ```python class RunBlackboard(models.Model): run = models.OneToOneField("Run", on_delete=models.CASCADE) data = models.JSONField(default=dict) ``` Wire: See Assembly templates templates; pairs with CAP-070. Test: `test_cap_073_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-080 · Step outcome capture Job: Persist learning fields on plan steps. Need when: Scenarios: optional. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-051 \| Pairs with: CAP-081 \| Module: `learning/` Contract - outcome_assessment, outcome_satisfaction, improvement_suggestion Code ```python class PlanStep(models.Model): outcome_assessment = models.TextField(blank=True) improvement_suggestion = models.TextField(blank=True) ``` Wire: See Assembly templates templates; pairs with CAP-051. Test: `test_cap_080_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-081 · Learned rules inject Job: Append-only rules prepended to foundation prompt. Need when: Scenarios: optional. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-020 \| Pairs with: — \| Module: `learning/` Contract - Human-reviewed before injection Code ```python def foundation_with_rules(base: str, rules: list[str]) -> str: return "\n".join(rules) + "\n\n" + base ``` Wire: See Assembly templates templates; pairs with CAP-020. Test: `test_cap_081_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. Status: sketch --- # CAP-090 · Reference RAG retrieval Job: Optional `search_knowledge` tool over Tier-4 document index (requires CAP-094 store). Need when: Tier 4 reference library selected; agent may pull framework/playbook chunks on demand. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-030,031 \| Pairs with: — \| Module: `knowledge/` Contract - LLM decides to call; empty hit is valid Code ```python def search_knowledge(query: str, , limit: int = 5) -> list[dict]: return index.query(query, top_k=limit) ``` Wire:* See Assembly templates templates; pairs with CAP-030. Test: `test_cap_090_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. Status: sketch --- # CAP-100 · SSE progress events Job: Typed SSE: typing, rate_limit, plan_step, ai_message. Need when: Scenarios: SC-01,03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-040 or 060 \| Pairs with: CAP-006 \| Module: `streaming/` Contract - Channel: `agent:stream:{conversation_id}` Code ```python def publish(event: str, payload: dict) -> None: redis.publish(f"agent:stream:{conversation_id}", json.dumps({"event": event, payload})) ``` Wire: See Assembly templates templates; pairs with loop/worker. Test: `test_cap_100_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. Status: sketch --- # CAP-110 · Event ingress Job: Domain event handler invokes agent factory or enqueues plan. Need when: Scenarios: SC-04. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-120 \| Pairs with: CAP-050 \| Module: `events/` Contract - Idempotent on event_id Code ```python def on_domain_event(event_id: str, payload: dict) -> None: if EventDedupe.seen(event_id): return agent = create_agent("responder") agent.handle_event(payload) ``` Wire: See Assembly templates templates; pairs with CAP-120. Test: `test_cap_110_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. Status: sketch --- # CAP-120 · Agent factory Job: Composition root wires LLM + tools + prompt + optional board. Need when: Scenarios: all. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-001,030,020 \| Pairs with: CAP-121 \| Module: `factory/` Contract** - `create_agent(identity, , llm=None)` Code* ```python def create_agent(identity: AgentIdentity, , llm: BaseLLM \| None = None): llm = llm or build_llm(tier=identity.model_tier) tools = ToolExecutor(build_registry(identity.allowed_tools)) prompt = PromptBuilder().with_identity(identity).build() return Agent(llm, tools, prompt) ``` Wire:* See Assembly templates templates. Test: `test_cap_120_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-121 · Agent identities Job: Frozen dataclass: tone, tools, model tier per persona. Need when: Scenarios: all. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-120 \| Pairs with: CAP-122 \| Module: `factory/` Contract - Identities are data, not subclasses Code ```python @dataclass(frozen=True) class AgentIdentity: name: str system_tone: str allowed_tools: frozenset[str] model_tier: str ``` Wire: See Assembly templates templates; pairs with CAP-120. Test: `test_cap_121_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- # CAP-122 · Model tier config Job: Named tiers planning/execution/field mapped to env model IDs. Need when: Scenarios: SC-01,02,03. Skip when: See Part 5 — Quick reference when this CAP is not in your scenario list. Requires: CAP-011,121 \| Pairs with: CAP-066 \| Module: `factory/` Contract - Field tier default max_tokens ≥ 8000 when thinking models Code ```python TIERS = {"planning": "claude-opus", "execution": "claude-sonnet", "field": "qwen3:14b"} def build_llm(tier: str) -> BaseLLM: return adapter_for(TIERS[tier]) ``` Wire: See Assembly templates templates; pairs with CAP-011. Test: `test_cap_122_smoke` Fails if: Capability omitted but scenario requires it — agent fails at runtime. --- ## 4.3 Module wiring Package map, forbidden imports, and dependency matrix are separate sections below. --- # Module wiring — package map ```text llm/ CAP-001–011 prompt/ CAP-020–023 tools/ CAP-030–036 context/ CAP-037–039 loop/ CAP-040–044 plan/ CAP-050–055 worker/ CAP-060–066 blackboard/ CAP-070–073 learning/ CAP-080–081 knowledge/ CAP-090–094 streaming/ CAP-100 events/ CAP-110 observability/ CAP-101 factory/ CAP-120–122 ``` --- # Module wiring — forbidden imports - `tools/` must not import `loop/` - `llm/` must not import domain apps - `loop/` must not own business rules — calls tools only - `context/` must not import `loop/` or `worker/` - `observability/` must not import domain mutation paths — record only --- # Module wiring — dependency matrix \| CAP \| 001 \| 008 \| 009 \| 031 \| 040 \| 050 \| 060 \| \|-----\|:---:\|:---:\|:---:\|:---:\|:---:\|:---:\|:---:\| \| CAP-009 \| ✓ \| ✓ \| — \| \| \| \| \| \| CAP-040 \| ✓ \| \| \| ✓ \| — \| \| \| \| CAP-044 \| \| \| \| \| ✓ \| ✓ \| ✓ \| \| CAP-060 \| ✓ \| \| \| ✓ \| \| ✓ \| — \| ```mermaid flowchart LR factory[factory_CAP-120] loop[loop_CAP-040] worker[worker_CAP-060] llm[llm_CAP-001] tools[tools_CAP-031] plan[plan_CAP-050] factory --> loop factory --> worker factory --> llm factory --> tools loop --> llm loop --> tools loop -->\|handoff\| plan worker --> plan worker --> tools worker --> llm ``` --- ## 4.4 Assembly templates Start from the template closest to your Scenario index scenario. Delete CAP wiring you did not select. --- # T-01 Planner (SC-01) CAP-IDs: 001,002,004,020,030,031,037,038,039,040,044,050,051,052,060,062,120,121 ```python # factory/agent_factory.py — T-01 Conversational planner (dual execution path) from dataclasses import dataclass from llm.base import BaseLLM, LLMMessage # CAP-001 from llm.scripted import ScriptedLLM # CAP-004 (tests only) from prompt.builder import PromptBuilder # CAP-020, CAP-021 from context.snapshot import SnapshotService # CAP-037, CAP-038 from tools.executor import ToolExecutor # CAP-030, CAP-031, CAP-039 from loop.react import bounded_react_loop # CAP-040, CAP-044 from plan.models import ExecutionPlan # CAP-050, CAP-051 from worker.tasks import execute_plan # CAP-060, CAP-062 @dataclass(frozen=True) class AgentIdentity: # CAP-121 name: str system_tone: str allowed_tools: frozenset[str] model_tier: str def create_agent(identity: AgentIdentity, , llm: BaseLLM \| None = None, mode: str = "conversation"): llm = llm or build_llm_for_tier(identity.model_tier) # CAP-011, CAP-122 tools = ToolExecutor( registry=build_tool_registry(identity.allowed_tools), mode=mode, # CAP-039: conversation \| workflow ) prompt = PromptBuilder().with_identity(identity).build() return PlannerAgent(llm=llm, tools=tools, prompt=prompt, snapshots=SnapshotService()) class PlannerAgent: def handle_message(self, user_id: int, text: str) -> str: snapshot = self.snapshots.get_or_build(user_id) # CAP-037 system = PromptBuilder().with_identity(...).with_context(snapshot=snapshot).build() return bounded_react_loop( # CAP-040, CAP-002 self.llm, self.tools, # CAP-039: WRITE_TOOLS only in conversation mode messages=[LLMMessage(role="user", content=text)], system=system, tool_schemas=build_tool_schemas(self.tools), # CAP-034 on_plan_created=self._enqueue_plan, # CAP-044, CAP-062 → worker uses mode=workflow ) ``` --- # T-02 Field (SC-02) CAP-IDs:* 001,004,008,009,020,030,031,120,121,122 ```python # factory/field_factory.py — T-02 Field extractor / bootstrap from llm.base import LLMMessage from llm.structured import extract_json_array # CAP-009 from prompt.builder import PromptBuilder # CAP-020 from tools.executor import ToolExecutor # CAP-031 def create_field_agent(, llm, tools: ToolExecutor, identity): return FieldAgent(llm=llm, tools=tools, prompt=PromptBuilder().with_identity(identity).build()) class FieldAgent: def extract_candidates(self, snapshot: str) -> list[dict]: resp = self.llm.complete( # CAP-001; adapter does CAP-008 [LLMMessage(role="user", content=snapshot)], system=self.prompt, max_tokens=8000, ) items = extract_json_array(resp.content) # CAP-009 if items is None: raise ExtractError("structured parse failed — fail loud, not silent zero-op") return items ``` --- # T-03 Pipeline (SC-03) CAP-IDs:* 001,002,004,020,050,051,053,060,061,062,120 ```python # worker/pipeline.py — T-03 Compiled pipeline from django.db import transaction from plan.models import ExecutionPlan from worker.tasks import execute_plan # CAP-060, CAP-062 def enqueue_compiled_plan(template_id: str, context: dict) -> int: plan = ExecutionPlan.from_template(template_id, context) # CAP-050 plan.save() transaction.on_commit(lambda: execute_plan.delay(plan.id)) return plan.id ``` --- # T-00 Custom Tick CAP-IDs in the capability table; copy matching specification blocks, wire in `factory/agent_factory.py`. --- ## 4.5 Integration proof Rule: Only CAP-004 ScriptedLLM may mock the LLM. Everything else uses real DB/services. \| Test ID \| Scenario \| Proves CAP-IDs \| Adverse? \| \|---------\|----------\|----------------\|----------\| \| PRF-SC02-01 \| SC-02 \| 008,009 — thinking-wrapped JSON → ops > 0 \| yes \| \| PRF-SC02-02 \| SC-02 \| 009 — parse fail must not exit 0 with zero side effects \| yes \| \| PRF-SC02-03 \| SC-02 \| Domain D0 pre-filter reduces candidate set deterministically \| no \| \| PRF-SC02-04 \| SC-02 \| D1 parse fail → non-zero exit, zero domain writes \| yes \| \| PRF-SC01-01 \| SC-01 \| 040,044,050,060 — message → plan → complete \| no \| \| PRF-SC01-02 \| SC-01 \| 061 — 429 retry; completed steps not re-run \| yes \| \| PRF-SC01-03 \| SC-01 \| 072 — bad LLM output retains blackboard \| yes \| \| PRF-SC05-01 \| SC-05 \| 033,036 — destructive tool blocked until approval \| yes \| \| PRF-SC05-02 \| SC-02+05 \| Full rescan: no hybrid graph; delete-before-add on natural key \| yes \| \| PRF-SC01-04 \| SC-01 \| 039 — conversation mode rejects read tools \| yes \| \| PRF-SC01-05 \| SC-01 \| 038 — mutation invalidates snapshot; next chat rebuilds \| no \| \| PRF-SC01-06 \| SC-01 \| 054 — mechanical step executor fails synthesis quality gate \| yes \| \| PRF-SC01-07 \| SC-01 \| 100 — worker failure emits plan_failed SSE/event \| yes \| \| PRF-OBS-01 \| all \| 101 — correlation_id in API log + LLM usage record \| no \| PRF-SC02-01 sketch: ```python def test_sc02_thinking_json_extract(scripted_llm, field_agent): scripted_llm.queue('{"message":{"thinking":"…","content":"[{\"name\":\"Api\"}]"}}') items = field_agent.extract_candidates("scan repo") assert len(items) == 1 assert items[0]["name"] == "Api" ``` PRF-SC02-03 sketch: ```python def test_sc02_d0_prefilter_drops_noise(): raw = [{"name": "Api", "path": "src/api.py"}, {"name": "test_foo", "path": "tests/test_foo.py"}] kept = d0_prefilter(raw, exclude_globs=["tests/"]) assert len(kept) == 1 assert kept[0]["name"] == "Api" ``` PRF-SC01-04 sketch: ```python def test_conversation_mode_blocks_read_tools(tool_executor): tool_executor.mode = "conversation" result = tool_executor.execute({"name": "list_entities", "arguments": {}}) assert result["success"] is False assert "not exposed" in result["error"] ``` PRF-SC01-05 sketch: ```python def test_mutation_invalidates_snapshot(snapshot_service, user_id): snap1 = snapshot_service.get_or_build(user_id) mutate_domain(user_id) snap2 = snapshot_service.get_or_build(user_id) assert snap2["version"] > snap1["version"] ``` PRF-SC01-06 sketch: ```python def test_mechanical_executor_fails_quality_gate(plan, mechanical_runner): with pytest.raises(SynthesisQualityError): mechanical_runner.execute_plan(plan) # no LLM per step ``` PRF-SC01-07 sketch: ```python def test_worker_failure_publishes_event(plan_id, event_bus): execute_plan(plan_id) # fails at step 2 events = event_bus.drain(channel=f"agent:stream:{conversation_id}") assert any(e["event"] == "plan_failed" for e in events) ``` PRF-OBS-01 sketch: ```python def test_correlation_id_in_llm_trace(client, caplog): resp = client.post("/api/chat/", headers={"X-Correlation-ID": "abc-123"}, ...) assert "abc-123" in caplog.text assert AgentInteraction.objects.filter(correlation_id="abc-123").exists() ``` PRF-SC05-02 sketch: ```python def test_rescan_delete_before_add_no_empty_graph(change_set_service, entity_model): existing = entity_model.objects.create(slug="api", name="Api") ops = rescan_operations(deletes=[existing.pk], adds=[{"slug": "api", "name": "Api v2"}]) change_set_service.apply(ops, rescan=True) assert entity_model.objects.filter(slug="api").count() == 1 assert entity_model.objects.get(slug="api").name == "Api v2" ``` Record chosen tests in project SAO §17 as the agent DoD gate. --- --- ## 3.4 Live eval profile (lane 3 — contract eval) When: After lane 1 PRF proofs green under CAP-004 ScriptedLLM; before promotion decisions that depend on live model behavior. Lane: 3 — Live contract eval (TFK-01 §6). Not lane 1 (orchestration) and not lane 4 (task quality oracle). LLM: Live provider at `temperature=0`. Do not use CAP-004 ScriptedLLM in lane 3 — scripted responses hide contract drift. Asserts — contract bounds only: - JSON/schema validation (CAP-008, CAP-009) — parse success, required keys, cardinality caps - Tool call envelope shape (name, arguments schema) — not tool selection correctness - Rate-limit / retry wiring surfaces expected status codes (optional subset) - No assistant-prose golden matching; no open-ended LLM-as-judge pass/fail Runner: `@pytest.mark.live_llm` in `tests/integration/agent/live/` or `tests/contract/agent/`. CI: `make test-agent-eval` → gated on `AGENTS_ENABLED=true`; schedule via separate `agent-eval.yml` — never default PR `ci.yml`. DoD relationship:** \| Gate \| Lane \| Blocks merge? \| \|------\|------\|---------------\| \| PRF-* ScriptedLLM \| 1 \| Yes (when `AGENTS_ENABLED`) \| \| Contract eval \| 3 \| No — nightly / optional CD cert \| \| TASK-* golden \| 4 \| No — promotion band \| Checklist - [ ] Tests marked `@pytest.mark.live_llm` and excluded from default `pytest tests/` collection - [ ] temp=0 set on provider client for eval runs - [ ] Contract asserts documented per test (schema file path or inline bounds) - [ ] Credentials via CI secrets / local `.env` — never committed - [ ] Failures triaged as contract/schema drift, not flaky chat wording --- ## 4.5 addendum — Run trace contract Lane 1 PRF proofs assert control-plane beats via `tests/support/agent_story.py` → `assert_agent_story(trace, workflow=..., beats={...})`. The trace recorder collects normalized events from the agent loop, ToolExecutor, and worker handoff — not raw LLM tokens. ### Trace fields \| Dimension \| Key / beat namespace \| Assert examples \| \|-----------\|---------------------\|-----------------\| \| Workflow \| `trace.workflow_id` \| `"munin_chat"`, `"ratatosk_field"`, `"execute_plan"` \| \| Tools \| `tools_offered`, `tools_called`, `tools_blocked` \| CAP-039: read tool blocked in conversation mode \| \| Domain \| `domain_writes`, `domain_reads`, `change_set_ops` \| element created; op count > 0 after SC-02 extract \| \| Board / plan \| `blackboard`, `plan_steps`, `plan_state` \| phase transition; step marked complete; CAP-072 retain on parse fail \| ### Beat vocabulary Align beat names with PRF sketches and BPE-01 Section G Trace beats to assert column: ```text entry \| config \| tools_offered \| tool_called \| tool_blocked \| tool_result \| domain_write \| domain_read \| plan_created \| plan_step \| plan_failed \| blackboard_set \| blackboard_retain \| rate_limit \| exit \| error ``` ### Helper contract ```python def assert_agent_story( trace, , workflow: str, beats: dict[str, list[str]], ) -> None: """Each beats[key] list must be non-empty when asserted; fail naming missing beat.""" ``` ### Rules 1. ScriptedLLM only* in lane 1 — queue paths under `tests/fixtures/llm_scripts/<prf-id>/`. 2. Assert names and outcomes, not assistant wording or chain-of-thought. 3. Happy + reject paths when PRF row is Adverse? yes or reject sketch exists. 4. Same commit as behavior — `checkpoint.agent_proof_command` when under PIN/MIN. ### Example (PRF-SC01-04) ```python @pytest.mark.agent_proof def test_prf_sc01_04_agent_story_reject(agent_harness, scripted_llm): scripted_llm.queue('{"content":"please list_entities"}') trace = agent_harness.run(workflow="munin_chat", mode="conversation", llm=scripted_llm) assert_agent_story(trace, workflow="munin_chat", beats={ "tools_blocked": ["list_entities"], "tool_result": ["list_entities:success=false"], }) ``` Record workflow id + beat columns in SAO §17 PRF table and BPE-01 Section G. --- ## 4.6 Golden task catalog (lane 4 — task performance quality) When: Promotion / regression monitoring — not PR merge DoD. Complements lane 1 PRF orchestration proofs. Purpose: Frozen inputs + structured ground truth measure whether model + prompt + tools produce correct domain outcomes (recall, graph diff, plan fidelity). ### Catalog fields (TASK-) \| Field \| Required \| Purpose \| \|-------\|----------\|---------\| \| `task_id` \| yes \| Stable id — `TASK-SC02-01`, `TASK-SC01-01` \| \| `sc_xx` \| yes \| Primary scenario — SC-01 … SC-05 \| \| `fixture_ref` \| yes \| Path to frozen input corpus under `tests/fixtures/agent_tasks/<task-id>/` \| \| `oracle_type` \| yes \| `set_recall` · `graph_diff` · `plan_steps` · `schema_bounds` · `hitl_rate` \| \| `pass_band` \| yes \| Structured thresholds — e.g. `min_recall: 0.95`, `max_extras: 1` \| \| `n_runs` \| no \| Stability across N runs at temp=0 (default 3 for promotion) \| \| `expected_ref` \| yes \| Golden YAML/JSON — names, ops, tool sequence, graph snapshot \| \| `adverse` \| no \| Whether reject-path corpus included \| \| `notes` \| no \| Human-readable scope / known flake \| ### Fixture layout ```text tests/fixtures/agent_tasks/TASK-SC02-01/ input/ # frozen repo snapshot or payload expected.yaml # structured oracle manifest.yaml # task_id, oracle_type, pass_band, n_runs ``` ### Starter catalog \| TASK ID \| Scenario \| Oracle type \| Pass band \| Proves \| \|---------\|----------\|-------------\|-----------\|--------\| \| TASK-SC02-01 \| SC-02 \| set_recall \| recall ≥ 0.95, extras ≤ 1 \| Field extract name set vs golden \| \| TASK-SC02-02 \| SC-02 \| graph_diff \| zero unexpected deletes on rescan corpus \| SC-02 × SC-05 rescan safety \| \| TASK-SC01-01 \| SC-01 \| plan_steps \| expected tool sequence + terminal plan state \| Planner fidelity \| \| TASK-SC05-01 \| SC-05 \| hitl_rate \| 100% destructive ops blocked until approval \| Governance overlay \| ### Runner - Marker: `@pytest.mark.quality` (+ `@pytest.mark.live_llm` when using live provider) - Target: `make test-agent-quality` when `AGENTS_ENABLED=true` - temp=0 on live runs; compare to last certified band* in SAO §17 — not bit-identical text ### Optional Deepeval overlay For SC-01 conversational tasks where structured oracle is insufficient (open-ended summarization, multi-sentence rationale): - Add Deepeval (or equivalent) metrics as a secondary signal — e.g. contextual relevancy, faithfulness to retrieved context - Never replace structured oracle for SC-02 field extract, graph diff, or HITL rate tasks - Deepeval failures → triage queue, not automatic merge block - Pin metric version + eval model in `manifest.yaml` when used ```python @pytest.mark.quality @pytest.mark.live_llm def test_task_sc02_01_recall_band(agent_harness, golden_task): results = [agent_harness.run_task(golden_task, temperature=0) for _ in range(golden_task.n_runs)] recalls = [golden_task.recall(r) for r in results] assert min(recalls) >= golden_task.pass_band["min_recall"] ``` Copy selected TASK rows to SAO §17 (DTA-19 §16). Skill: Agent Task Eval. --- --- # Part 5 — Quick reference ## Scenario index \| ID \| Name \| When (biz words) \| CAP-IDs (required) \| CAP-IDs (optional) \| \|----\|------\|------------------\|--------------------\|--------------------\| \| SC-01 \| Conversational planner \| User chats; agent calls tools; work beyond one tool call becomes a background job \| 001,002,004,020,030,031,040,044,050,051,060,062,120,121 \| 003,005,006,007,010,033,037,038,039,042,043,052,053,054,061,066,070,091,092,093,100,101 \| \| SC-02 \| Field extractor / batch ingest \| Scripted chain: D0 pre-filter → D1 LLM canonicalize → propose writes; no chat loop \| 001,004,008,009,020,030,031,120,121,122 \| 005,011,023,032,036,090,091,094 \| \| SC-03 \| Compiled pipeline \| Trigger fires known step graph; selective LLM on some steps \| 001,002,004,020,050,051,053,060,061,062,120 \| 054,066,100,101 \| \| SC-04 \| Event-driven nudge \| Domain event → agent message/plan without user opening chat \| 001,002,040,110,120 \| 050,060,100,101 \| \| SC-05 \| Governed mutations \| Agent proposes writes; human approves destructive ops \| 001,030,031,033,036 \| 040,050,032 \| ## Pattern picker ```text Need structured JSON from LLM? yes → Pattern 2 (SC-02) + CAP-008, CAP-009 User conversation drives work? yes → Pattern 4 (SC-01) Work survives request / crash? yes → CAP-050, CAP-060, CAP-062 Known step graph at trigger time? yes → Pattern 7 (SC-03) Proactive on domain events? yes → Pattern 3 (SC-04) Human approves deletes/mutations? yes → Pattern 5 (SC-05) External IDE/agent tools via MCP? yes → Pattern 6 + MCP FastMCP Reference Architecture Large domain state in chat? yes → CAP-037, CAP-039 (required when large; default in T-01) Semantic lookup in large history? yes → CAP-091 Persistent user profile? yes → CAP-092 Reference docs/playbooks on demand? yes → CAP-094 (+ CAP-090) Production deployment? yes → CAP-101 Background steps call LLM? yes → CAP-053, CAP-054, CAP-066 (mandatory per Pattern 4 anti-patterns) ``` ## Memory tier picker ```text All state fits in one JSON snapshot? yes → Tier 1 only (CAP-037–039) Need NL search over entities? yes → Tier 2 (CAP-091) Cross-session preferences? yes → Tier 3 (CAP-092) Uploaded reference library? yes → Tier 4 (CAP-094, CAP-090) Recurring entity notes? yes → Tier 5 (CAP-093) ``` ## Serving mode picker ```text User waiting on chat response? yes → Part 3.1 Real-time (CAP-040, CAP-003, CAP-100) Batch CLI / CI / async plans? yes → Part 3.2 Batch/queue (CAP-060–066) Both? wire CAP-044 handoff + worker path ``` --- End of Artifact 56 — AI Agent Reference Architecture
System Architecture Overview Template	Document	Write SAO.md Define Architecture	Optional	13	Read the 'System Architecture Overview Template' artifact from playbook 'Junior Edda'. Type: Document. Required: false. # {Project Name}: System Architecture Overview ## Executive Summary - System purpose (1-2 sentences) - Key architectural decisions (bullet list of the most impactful choices) ## 1. Application Blocks <!-- Decision from DTA-02 --> ### Bounded Contexts / Domain Packages - List domain packages with responsibilities ### Module Dependency Rules - Dependency direction diagram or rules ### Foundational Architectural Pattern - Chosen: {pattern} - Rationale: Why this pattern over alternatives ### UI Architecture Patterns (if applicable) - Rendering model: {server-rendered \| SPA \| hybrid} — rationale - Layout pattern: {single-panel \| multi-panel \| wizard} — rationale - Component interaction model: {full reload \| partial updates \| client-side state} — rationale - Visualization approach: {server-generated \| client-rendered \| hybrid} — rationale ## 2. Integration & API Design <!-- Decision from DTA-03 --> ### API Style - Chosen: {style} - Rationale: Why this style ### Versioning Strategy - Chosen: {strategy} ### Contract Approach - Chosen: {approach} ### External Integrations - List 3rd party APIs, webhook patterns, retry policies ### Inter-Service Communication - Chosen: {model} - Rationale: Why this model ### Implementation Patterns <!-- Populated during/after implementation --> - Service-to-transport mapping: - Sync/async boundary: - Protocol-specific constraints: - Shared service layer: - Error propagation: ## 3. Code Organization <!-- Decision from DTA-04 --> ## 4. Data Architecture <!-- Decision from DTA-05 --> ## 5. Test Strategy <!-- Decision from DTA-06 — seed broad strokes (Trophy, frameworks, CI gates); TFK-01 fleshes layout, gates, and quality workflow before BPE. --> <!-- When §17 AI Agent Architecture applies (not "Not applicable"): seed four agent test lanes in this section (1 control-plane proofs, 2 deterministic shell, 3 live contract eval, 4 task performance quality). Follow DTA-06 activity for the seed table; TFK-01 fleshes lane wiring, PRF vs TASK mapping, Makefile/CI targets, and pytest markers. When §17 is N/A, omit agent lanes. --> ## 6. Performance & Scalability <!-- Decision from DTA-07 --> ## 7. Error Handling & Resilience <!-- Decision from DTA-08 --> ## 8. Infrastructure <!-- Decision from DTA-09 --> ## 9. CI/CD Pipeline <!-- Decision from DTA-10 --> ## 10. Release & Rollback <!-- Decision from DTA-11 --> ## 11. Observability <!-- Decision from DTA-12 --> ## 12. Config & Secrets <!-- Decision from DTA-13 --> ## 13. Security <!-- Decision from DTA-14 --> ## 14. Backup & Recovery <!-- Decision from DTA-15 --> ## 15. Developer Experience <!-- Decision from DTA-16 --> ## 16. Documentation Strategy <!-- Decision from DTA-17 --> ## 17. AI Agent Architecture <!-- Decision from DTA-19 — omit this section if no in-app agent --> <!-- Skip condition: write "Not applicable — no in-app LLM agent." and remove the subsections below if DTA-19 was not run. Reference: Playbook artifact AI Agent Reference Architecture — Parts 1–5 and Part 4 capability appendix --> ### Infra layer (Part 1 · Component 1) \| Setting \| Value \| \|---------\|-------\| \| LLM provider \| \| \| Ollama host / model (if applicable) \| \| \| API key storage \| server env / secret manager \| \| Celery broker URL (if CAP-060) \| \| \| Celery result backend \| \| \| LLM readiness health check \| Yes / No \| ### Vector tier (Part 1 · Component 3) \| Decision \| Value \| \|----------\|-------\| \| Vector store used \| Yes / No \| \| Backend \| pgvector / dedicated / in-process \| \| Embedding model \| \| \| CAP-090 search_knowledge \| Yes / No \| \| CAP-094 reference library \| Yes / No \| ### Design pattern & scenario selection <!-- Read Part 2 patterns in the AI Agent Reference Architecture before ticking --> \| 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 \| \| \| ### Serving mode (Part 3) \| Mode \| Selected? \| Notes \| \|------\|-----------\|-------\| \| Real-time (3.1) — sync chat, streaming \| \| CAP-040, CAP-003, CAP-100 \| \| Batch / queue (3.2) — worker, CI ingest \| \| CAP-060–066 \| \| Observability for serving (3.3) \| \| CAP-101, CAP-100 events \| ### Dual execution path (Pattern 4 / SC-01) \| Decision \| Choice \| Rationale \| \|----------\|--------\|-----------\| \| Context snapshot in chat (CAP-037) \| \| \| \| Snapshot invalidation (CAP-038) \| \| \| \| Mutation-only conversation tools (CAP-039) \| \| \| \| Full tools in worker only \| \| \| ### Memory tiers (Part 1 · Component 5) \| Tier \| CAP-IDs \| Selected? \| Rationale \| \|------\|---------\|-----------\|-----------\| \| 1 Hot snapshot \| 037–039 \| \| \| \| 2 Semantic search \| 091 \| \| \| \| 3 AI profile \| 092 \| \| \| \| 4 Reference library \| 094, 090 \| \| \| \| 5 Entity notes \| 093 \| \| \| ### Capability checklist <!-- Copy CAP rows from Part 4.1 for every CAP implemented --> \| CAP-ID \| Name \| Implement? \| Project module path \| \|--------\|------\|--------------\|---------------------\| \| CAP-001 \| LLM Port protocol \| \| \| \| CAP-004 \| ScriptedLLM \| \| \| \| CAP-037 \| Context snapshot hydration \| \| \| \| CAP-038 \| Snapshot invalidation hooks \| \| \| \| CAP-039 \| Dual tool exposure \| \| \| \| CAP-091 \| Semantic context search \| \| \| \| CAP-101 \| Agent interaction trace \| \| \| \| \| \| \| \| ### Assembly template - Template: {T-01 Planner \| T-02 Field \| T-03 Pipeline \| T-00 Custom} - Custom CAP list (if T-00): CAP-___ , CAP-___ , … ### Agent identities (CAP-121 / CAP-122) \| Identity \| Role \| Model tier \| Allowed tools \| \|----------\|------\|------------\|---------------\| \| \| \| planning / execution / field \| \| ### Agent Blackboard (if CAP-070 selected) \| Key \| Role \| Durability \| \|-----\|------\|-----------\| \| \| \| \| - Durability tier: {A — in-process \| B — run-persistent} - Max board size (chars): ______ ### Plan & Steps (if CAP-050 selected) - States: `pending → running → completed \| failed \| waiting_retry` - Hybrid step flags in use: {is_critical, is_planning, is_variable_assessment, data-only} - Worker uses LLM per step (CAP-054) — not mechanical tool-only execution ### Worker failure bridge (if CAP-060 selected) - [ ] CAP-100 plan_failed event and/or chat context injection on worker failure - [ ] PRF-SC01-07 mapped to integration test file ### Observability (Part 1 · Component 6 / CAP-101) \| Field \| Value \| \|-------\|-------\| \| correlation_id header \| \| \| Cost rate table location \| \| \| PRF-OBS-01 test file \| \| ### Integration proof (DoD gate) <!-- Map PRF-SCxx-xx test IDs from Part 4.5 --> \| PRF ID \| Scenario \| Test file \| \|--------\|----------\|-----------\| \| 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-OBS-01 \| all — correlation + usage trace \| \| \| PRF-SC05-01 \| SC-05 HITL \| \| \| PRF-SC05-02 \| SC-02+05 full rescan invariants \| \| ### SC-02 × SC-05 full rescan (if batch ingest replaces snapshot) Complete when both SC-02 and SC-05 are selected: - [ ] 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 ## 18. MCP Architecture <!-- Decision from DTA-20 — omit this section if no MCP interface --> <!-- Skip condition: write "Not applicable — no MCP interface." and remove the subsections below if DTA-20 was not run. Reference: Playbook artifact MCP FastMCP Reference Architecture --> ### Integration Case - Chosen: {Case A — Service Bridge \| Case B — API Facade \| Hybrid} - Rationale: _____ ### Transport Topology \| Target \| Transport \| Port / Path \| Notes \| \|--------\|-----------\|------------\|-------\| \| Local IDE \| stdio \| n/a \| \| \| Remote AI clients \| HTTP+SSE \| \| \| ### Tool Inventory \| Tool name \| Service method \| Write? \| HITL? \| Case \| \|-----------\|---------------\|--------\|-------\|------\| \| \| \| \| \| \| - Write-tool policy: {Require explicit confirmation param \| HITL prompt before execute \| Audit log only} ### Auth Pattern - Selected: {Process user \| PAT per call \| Session cookie \| Mixed} - PAT injection point: {Tool argument \| HTTP header (Bearer)} - Rationale: _____ ### Stdout Hygiene (if stdio) - Logging redirected to stderr / file: {Yes \| N/A} - Third-party stdout suppressed: {Yes \| N/A} - Boot noise test added: {Yes \| N/A} ### API Readiness Contract (if Case B) \| Tool \| HTTP endpoint \| Method \| Auth header \| \|------\|--------------\|--------\|-------------\| \| \| \| \| \| ## Technology Stack Table Machine-readable table consumed by Bootstrap Project (BSP) for automated provisioning. \| Layer \| Tool \| Version \| Install Command (macOS) \| Install Command (Linux) \| Verify Command \| \|-------\|------\|---------\|-------------------------\|-------------------------\|----------------\| \| ... \| ... \| ... \| ... \| ... \| ... \| > Note: Each row must have install + verify commands so BSP can automate provisioning. ## Skill Coverage Report \| Domain \| Covered Skills \| Gaps \| \|--------\|---------------\|------\| \| Application Blocks \| \| \| \| Integration & API \| \| \| \| Code Organization \| \| \| \| Data Architecture \| \| \| \| Test Strategy \| \| \| \| Performance & Scalability \| \| \| \| Error Handling & Resilience \| \| \| \| Infrastructure \| \| \| \| CI/CD Pipeline \| \| \| \| Release & Rollback \| \| \| \| Observability \| \| \| \| Config & Secrets \| \| \| \| Security \| \| \| \| Backup & Recovery \| \| \| \| Developer Experience \| \| \| \| Documentation Strategy \| \| \| \| AI Agent Architecture \| \| \| \| MCP Architecture \| \| \| ## Key Decisions with Rationale \| # \| Domain \| Decision \| Rationale \| \|---\|--------\|----------\|-----------\| \| 1 \| \| \| \| ## Discovered Patterns & Lessons Learned <!-- Reserved section — populated during and after implementation --> ### Critical Discoveries <!-- For each significant discovery during implementation: --> <!-- #### Discovery: {title} - Context: What was being built/integrated - Problem: What didn't work as expected - Solution: The pattern/workaround adopted - Key Lessons: 1. ... --> ### Retrospective Updates <!-- Track SAO sections updated post-implementation: --> <!-- \| Section \| Original Decision \| What Changed \| Updated Decision \| \|---------\|-------------------\|--------------\|------------------\| \| \| \| \| \| -->

Artifacts in Junior Edda