Elaboration - Junior Edda

Description

Elaboration phase translates the Inception architecture into a working, deployable system. All workflows in this phase depend on DTA outputs from Inception. Workflow execution sequence: (1) DSP - Define Software Process: consumes SAO.md to define branching strategy, tooling, and Definition of Done. Must run first as it establishes process conventions used by all subsequent workflows. (2) EST - Estimate the Project: can run in parallel with DCI once DSP is complete. (3) DCI - Define Cloud Infrastructure: provisions AWS infrastructure (VPC, EKS, ECR, Route53) that DCD depends on. (4) DCD - Define CD Pipeline: builds Helm charts and CI/CD pipelines on top of DCI infrastructure. Must complete before BSP. (5) BSP - Bootstrap Project: scaffolds the runnable application using the Makefile, pipeline, and conventions established by DSP, DCI, and DCD. Parallel group: EST can run alongside DCI. Sequential constraint: DCI must complete before DCD, DCD must complete before BSP.

Activities in this Phase

Order	Name	Actions
Deploy Software Process
#1	Verify ESM Artifacts	Read the 'DSP-1 Verify ESM Artifacts' activity from playbook 'Junior Edda' (workflow 'Deploy Software Process'). Follow its guidance when assisting me. # Verify ESM Artifacts ## Objective Verify that all required artifacts from the Envision the System (ESM) workflow exist before proceeding to AI IDE configuration. If any are missing, direct the user to run the ESM workflow first. --- ## Process ### 1. Scan for Required ESM Artifacts Check for the existence and non-emptiness of: \| Artifact \| Expected Location \| ESM Activity \| \|----------\|-------------------\|--------------\| \| User Journey \| `docs/features/user_journey.md` \| ESM-02 \| \| Dialogue Maps / Screen Flows \| `docs/ux/` (at least one `.drawio` or screen flow file) \| ESM-04 \| \| Feature Files \| `docs/features/act-/` (at least one `.feature` file or scenario markdown) \| ESM-05 \| \| IA Guidelines* \| `docs/ux/IA_guidelines.md` \| ESM-03 \| ### 2. Evaluate Results For each artifact, report status: ``` ESM Artifact Check: User Journey \| ✅ Found (docs/features/user_journey.md, 104KB) Dialogue Maps \| ✅ Found (docs/ux/2_dialogue-maps/, 3 files) Feature Files \| ✅ Found (docs/features/act-/, 12 acts) IA Guidelines \| ❌ Missing ``` ### 3. If Any Missing → Redirect to ESM If one or more artifacts are missing: > ⚠️ ESM artifacts incomplete.* > The following are missing: {list}. > Please run the Envision the System (ESM) workflow first. > See: `.windsurf/workflows/ESM/_workflow.md` Stop here — do not proceed to DSP-02 until all ESM artifacts are present. ### 4. If All Present → Proceed > ✅ All ESM artifacts verified. Proceeding to DSP-02 (Verify DTA Artifacts). --- ## Deliverables - ✅ ESM artifact checklist evaluated - ✅ All artifacts present — or user redirected to ESM workflow - ✅ Ready to proceed to DSP-02
#2	Verify DTA Artifacts	Read the 'DSP-2 Verify DTA Artifacts' activity from playbook 'Junior Edda' (workflow 'Deploy Software Process'). Follow its guidance when assisting me. # Verify DTA Artifacts ## Objective Verify that the System Architecture Overview (SAO.md) from the Define Architecture (DTA) workflow exists and contains the required architectural decisions. If missing, direct the user to run the DTA workflow first. --- ## Process ### 1. Scan for SAO.md Check for existence and non-emptiness of: \| Artifact \| Expected Location \| DTA Activity \| \|----------\|-------------------\|--------------\| \| SAO.md \| `docs/architecture/SAO.md` \| DTA-18 \| ### 2. Validate SAO.md Content If the file exists, verify it contains key sections (search for headings): \| Required Section \| Purpose \| Used By DSP-05 \| \|-----------------\|---------\|-----------------\| \| Executive Summary \| Project overview for AI config \| Yes — project description \| \| System Architecture \| High-level components \| Yes — architecture section \| \| Design Principles \| Key decisions \| Yes — coding conventions \| \| Technology Stack or equivalent \| Languages, frameworks, tools \| Yes — tech stack reference \| \| Project Structure \| Directory layout \| Yes — directory map \| \| Testing Infrastructure \| Test strategy \| Yes — testing conventions \| Report status: ``` DTA Artifact Check: SAO.md exists \| ✅ Found (docs/architecture/SAO.md, 2671 lines) Executive Summary \| ✅ Present System Architecture \| ✅ Present Design Principles \| ✅ Present Technology Stack \| ❌ Missing — no explicit tech stack table Project Structure \| ✅ Present Testing Infrastructure \| ✅ Present ``` ### 3. If SAO.md Missing or Incomplete → Redirect to DTA If SAO.md does not exist: > ⚠️ SAO.md not found. > Please run the Define Architecture (DTA) workflow first. > See: `.windsurf/workflows/DTA/_workflow.md` If SAO.md exists but is missing key sections: > ⚠️ SAO.md incomplete. > Missing sections: {list}. > Please complete the relevant DTA activities: {activity list}. Stop here — do not proceed to DSP-03 until SAO.md is complete. ### 4. If Complete → Proceed > ✅ SAO.md verified with all required sections. Proceeding to DSP-03 (Verify Architecture & Code Organization). --- ## Deliverables - ✅ SAO.md existence verified - ✅ SAO.md content validated for required sections - ✅ All sections present — or user redirected to DTA workflow - ✅ Ready to proceed to DSP-03
#3	Verify Architecture & Code Organization	Read the 'DSP-3 Verify Architecture & Code Organization' activity from playbook 'Junior Edda' (workflow 'Deploy Software Process'). Follow its guidance when assisting me. # Verify Architecture & Code Organization ## Objective Verify that the project has a defined code organization, technology stack, and working project structure. This goes beyond SAO.md existence (DSP-02) to check that the architectural decisions have been realized in the actual codebase or are clearly documented for a greenfield project. --- ## Process ### 1. Check Project Structure Exists For an existing project, verify: \| Check \| What to Look For \| Source \| \|-------\|------------------\|--------\| \| Project root \| `manage.py`, `package.json`, `Cargo.toml`, or equivalent entry point \| DTA-04 \| \| Source directories \| Application code directories matching SAO.md structure \| DTA-04 \| \| Test directories \| `tests/` or equivalent with at least one test file \| DTA-06 \| \| Dependency file \| `requirements.txt`, `package.json`, `Cargo.toml`, etc. \| DTA-04 \| \| CI/CD config \| `.github/workflows/`, `Jenkinsfile`, etc. (optional for greenfield) \| DTA-10 \| For a greenfield project (no code yet), verify that SAO.md contains: - Explicit directory layout plan (from DTA-04) - Technology stack decisions (languages, frameworks, databases) - These will be used by BSP (Bootstrap Project) workflow to create the structure ### 2. Check Workflow & Skill Coverage Scan `.windsurf/workflows/` for available workflows: ``` Available Workflows: ESM \| Envision the System \| 7 activities \| ✅ DTA \| Define Architecture \| 18 activities \| ✅ DSP \| Deploy Software Process \| 6 activities \| ✅ (this workflow) BSP \| Bootstrap Project \| 8 activities \| ✅ BPE \| Build Feature \| N activities \| ✅ EST \| Estimate the Project \| 8 activities \| ✅ ``` Scan for available skills (if any exist in workflow `skills/` directories): ``` Available Skills: BSP/skills/ \| 3 skills found (others) \| ... ``` Scan for available artifact templates: ``` Available Artifact Templates: ESM/artifacts/ \| user_journey_template.md, feature_file_template.feature, ... DTA/artifacts/ \| sao_document_template.md DSP/artifacts/ \| claude_md_template.md, copilot_instructions_template.md, ... ``` ### 3. Evaluate Readiness Ready to proceed if: - SAO.md has technology stack and directory layout (from DSP-02) - Either project structure exists OR SAO.md documents the planned structure - At least BPE workflow is available (the AI needs to know how to build features) Not ready if: - No technology stack defined in SAO.md → redirect to DTA-02 (Define Application Blocks) - No directory layout in SAO.md → redirect to DTA-04 (Define Code Organization) - No BPE workflow available → this is a critical gap, inform user ### 4. Report Summary ``` Architecture & Code Organization Check: Technology stack defined \| ✅ Django 5 + SQLite + HTMX Directory layout defined \| ✅ In SAO.md Section "Project Structure" Project structure exists \| ✅ 4 Django apps, tests/, docs/ BPE workflow available \| ✅ .windsurf/workflows/BPE/ Skills available \| ✅ 3 skills in BSP/skills/ Artifact templates \| ✅ 7 templates across workflows ``` --- ## Deliverables - ✅ Project structure verified or planned - ✅ Workflow coverage inventoried - ✅ Skill coverage inventoried - ✅ Artifact template coverage inventoried - ✅ All prerequisites met — or user redirected to specific DTA/ESM activities - ✅ Ready to proceed to DSP-04
#4	Choose Target AI IDE	Read the 'DSP-4 Choose Target AI IDE' activity from playbook 'Junior Edda' (workflow 'Deploy Software Process'). Follow its guidance when assisting me. # Choose Target AI IDE ## Objective Ask the user which AI-assisted IDE they will use for development, then record the choice to determine the output format for DSP-05 (Generate AI IDE Configuration). --- ## Process ### 1. Present Options Ask the user to choose their primary AI IDE: \| Target \| Output File(s) \| Format \| \|--------\|----------------\|--------\| \| Claude Code \| `CLAUDE.md` at project root \| Single Markdown file with all context \| \| GitHub Copilot \| `.github/copilot-instructions.md` \| Single Markdown file in `.github/` \| \| Windsurf \| `.windsurf/rules/.md` files \| Multiple rule files + workflow references \| \| Cursor* \| `.cursor/rules/.mdc` files \| Multiple rule files in MDC format \| ### 2. Clarify Multi-IDE Usage If the user works with multiple IDEs (e.g., Windsurf for daily work + Claude Code for complex tasks): - Generate configs for all selected targets* - Ensure consistency across configs (same conventions, same references) - Note: Windsurf and Cursor share the same workflow/rule structure but use different directories ### 3. Record Choice Document the selected target(s) for DSP-05: ``` Target AI IDE Selection: Primary: Windsurf Secondary: Claude Code Output files to generate: 1. .windsurf/rules/ (multiple .md files) 2. CLAUDE.md (single file) ``` ### 4. Confirm Output Structure Explain to the user what will be generated: For Claude Code / GitHub Copilot (single file): - One comprehensive Markdown file covering: - Project overview and architecture - Directory layout and docs map - Available workflows, skills, and artifact templates - AI/human collaboration patterns and quality gates - Coding conventions and testing discipline - How to build features (BPE workflow reference) - How to run locally For Windsurf / Cursor (multiple files): - The project already uses `.windsurf/rules/` and `.windsurf/workflows/` — these ARE the config - DSP-05 will audit and supplement existing rules to ensure completeness - A summary `_ai-context.md` rule file will be generated pointing to all docs, workflows, skills, and templates - Existing rules will NOT be overwritten --- ## Deliverables - ✅ Target AI IDE selected (one or more) - ✅ Output format understood by user - ✅ Ready to proceed to DSP-05 (Generate AI IDE Configuration)
#5	Generate AI IDE Configuration	Read the 'DSP-5 Generate AI IDE Configuration' activity from playbook 'Junior Edda' (workflow 'Deploy Software Process'). Follow its guidance when assisting me. # Generate AI IDE Configuration ## Objective Assemble a comprehensive configuration file for the chosen AI IDE target, pulling from SAO.md, ESM artifacts, available workflows, skills, artifact templates, and coding conventions. The output file gives the AI agent everything it needs to understand the project and start building features. --- ## Process ### 1. Gather Inputs Collect all source material identified in DSP-01 through DSP-03: \| Source \| What to Extract \| Config Section \| \|--------\|----------------\|----------------\| \| `docs/architecture/SAO.md` \| Executive summary, architecture, design principles, tech stack, directory layout \| Sections 1-3 \| \| `docs/features/user_journey.md` \| Acts, user journey overview \| Section 4 (Docs Map) \| \| `docs/features/act-/` \| Feature file inventory \| Section 4 (Docs Map) \| \| `docs/ux/IA_guidelines.md` \| UI patterns, design system \| Section 4 (Docs Map) \| \| `.windsurf/workflows//` \| Workflow names, descriptions, activity counts \| Section 5 (Workflows) \| \| `.windsurf/workflows//skills/` \| Skill titles, capability domains, tech stacks \| Section 6 (Skills) \| \| `.windsurf/workflows//artifacts/` \| Template file names and descriptions \| Section 7 (Artifact Templates) \| \| `.windsurf/rules/.md` \| Coding conventions, testing discipline, commit format \| Section 9 (Conventions) \| ### 2. Assemble Config File Use the appropriate template from `DSP/artifacts/` based on the target chosen in DSP-04. The config file MUST contain these sections (section numbers vary by template): #### Section: What Is {ProjectName} Extract from SAO.md Executive Summary. One paragraph explaining what the project does and its key innovation. #### Section: Architecture Extract from SAO.md: - High-level component diagram (ASCII or Mermaid) - Directory layout (from Project Structure section) - Data model hierarchy - Key design decisions (top 3-5) #### Section: Documentation Map Point to all key docs with brief descriptions: ```markdown \| 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 \| \| Agent reference architecture \| Playbook artifact 56 \| When SAO §17 applies \| \| Test architecture (TFK-01) \| `docs/architecture/test-architecture.md` \| Agent test lanes, CI gates \| ``` When SAO §17 applies, add agent-lane rows to the docs map: ```markdown \| Agent integration proofs (PRF-) \| skill Agent Integration Proof Patterns* \| Before agent slices \| \| Agent task eval (TASK-) \| skill Agent Task Eval* \| Promotion / nightly only \| \| assert_agent_story helper \| `tests/support/agent_story.py` \| TFK-02 bootstrap \| ``` #### Section: Available Workflows List each workflow with its purpose, activity count, and when to use it: ```markdown \| Workflow \| Purpose \| Activities \| When to Use \| \|----------\|---------\|------------\|-------------\| \| ESM \| Envision the System \| 7 \| Defining what to build \| \| DTA \| Define Architecture \| 18 \| Making architectural decisions \| \| DSP \| Deploy Software Process \| 6 \| Setting up AI IDE \| \| BSP \| Bootstrap Project \| 8 \| Scaffolding new project \| \| BPE \| Build Feature \| N \| Primary workflow for feature delivery \| \| EST \| Estimate the Project \| 8 \| Estimation and planning \| ``` #### Section: Available Skills List skills found in workflow `skills/` directories: ```markdown \| Skill \| Capability Domain \| Tech Stack \| Location \| \|-------\|-------------------\|------------\|----------\| \| {SkillTitle} \| {Domain} \| {Stack} \| `.windsurf/workflows/{WF}/skills/{file}` \| ``` When SAO §17 applies, ensure these agent-test skills appear in the inventory (link from playbook, do not duplicate bodies): ```markdown \| Agent Integration Proof Patterns \| TEST_INTEGRATION \| pytest, CAP-004, artifact-56 \| playbook skill \| \| Agent Task Eval \| TEST_INTEGRATION \| golden-tasks, live LLM \| playbook skill \| \| Pytest Log Story Assertions \| LOG_STORY_TESTING \| pytest caplog \| playbook skill \| \| Test Trophy Architecture \| TEST_STRATEGY \| pytest+behave \| playbook skill \| \| pytest Runner Configuration \| TEST_FRAMEWORK \| pytest markers \| playbook skill \| ``` If no skills exist yet, note: "No skills defined yet. Skills provide technology-specific implementation guidance for workflow activities." #### Section: Artifact Templates List templates found in workflow `artifacts/` directories: ```markdown \| Template \| Workflow \| Purpose \| Location \| \|----------\|----------\|---------\|----------\| \| User Journey Template \| ESM \| Structure for user journey doc \| `ESM/artifacts/user_journey_template.md` \| \| IA Guidelines Template \| ESM \| Design system & UI patterns spec \| `ESM/artifacts/ia_guidelines_template.md` \| \| Feature File Template \| ESM \| BDD scenario format \| `ESM/artifacts/feature_file_template.feature` \| \| SAO Template \| DTA \| Architecture document structure \| `DTA/artifacts/sao_document_template.md` \| \| CLAUDE.md Template \| DSP \| AI config for Claude Code \| `DSP/artifacts/claude_md_template.md` \| \| Copilot Instructions Template \| DSP \| AI config for GitHub Copilot \| `DSP/artifacts/copilot_instructions_template.md` \| \| Windsurf/Cursor Rules Template \| DSP \| AI config for Windsurf/Cursor \| `DSP/artifacts/windsurf_cursor_rules_template.md` \| \| Makefile Template \| BSP \| Project orchestration Makefile \| `BSP/artifacts/makefile_template.mk` \| \| Helm Chart Template \| DCD \| K8s Helm chart structure \| `DCD/artifacts/` (reference structure) \| \| Infra Repo Scaffold \| DCI \| CDK infra repo structure \| `DCI/artifacts/` (reference structure) \| \| Implementation Plan Template \| BPE \| Feature implementation plan \| `BPE/artifacts/implementation_plan_template.md` \| \| Definition of Done Checklist Template \| BPE \| DoD checklist for feature sign-off \| `BPE/artifacts/definition_of_done_checklist_template.md` \| \| AI Agent Reference Architecture \| DTA \| CAP-, PRF-, TASK-* catalogs \| `DTA/artifacts/` artifact 56 \| ``` #### Section: AI/Human Collaboration Patterns Absorbed from the former DSP-05 content. Include: AI Agent Responsibilities: - Code generation following established patterns - Test implementation (unit, integration, e2e) - Documentation generation (docstrings, README updates) - Refactoring within architectural boundaries 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 patterns → ask human - Security-sensitive code → flag for human review #### Section: Coding Conventions Extract from `.windsurf/rules/` or document directly: - Commit format (Angular convention) - Method size limits (20-30 lines max for public methods) - Import organization (module-level only) - Logging standards (INFO level, what/why/where/when) - Testing discipline (test-first, pytest, no mocks in integration tests except CAP-004 ScriptedLLM in `@agent_proof` tests) When SAO §17 applies, append agent test lane conventions: ```markdown ### Agent test lanes (SAO §17) \| Lane \| Gate \| Command \| Rule / skill \| \|------\|------\|---------\|--------------\| \| 1 Control-plane proofs \| PR when AGENTS_ENABLED \| `make test-agent-proof` \| `do-assert-agent-story`, Agent Integration Proof Patterns \| \| 2 Deterministic shell \| PR integration \| normal `make test` \| no LLM mock \| \| 3 Live contract eval \| Nightly / CD optional \| `agent-eval.yml` \| temp=0 contracts \| \| 4 Task performance \| Promotion \| `make test-agent-quality` \| Agent Task Eval, not PR merge \| - Behave AT proves user-visible behavior; `@pytest.mark.agent_proof` proves PRF orchestration — do not merge them. - Ban FakeLLM and silent queue exhaustion — CAP-004 ScriptedLLM only (`do-not-mock-in-integration-tests`). - Plan slices declare Agent Proof Table (BPE-01 Section G); MIN manifest may set `checkpoint.agent_proof_command`. ``` #### Section: Development Workflow (How to Build Features) Reference the BPE workflow with a condensed summary: 1. Read the feature spec in `docs/features/act-/` 2. Read SAO.md for architectural context 3. Backend: models → services → views 4. Frontend: templates + interactions 5. Tests: write before implementation, 100% pass rate required 6. When SAO §17: behavior + log story + agent proof green in same slice 7. PR with all changes #### Section: Running Locally Extract from SAO.md or document: - Setup commands (venv, install, migrate) - Start dev server - Run tests - Load demo data When SAO §17 applies, append agent test commands: ```bash make test-agent-proof # lane 1 PRF proofs (no-op when AGENTS_ENABLED unset) make test-agent-quality # lane 4 TASK- eval (nightly / manual) pytest -m agent_proof tests/integration/agent/ -x ``` ### 3. Customize for Target Format Claude Code (`CLAUDE.md`): - Single file, flat Markdown sections with `---` separators - Use `##` for main sections - Keep under ~500 lines (Claude Code reads this on every conversation) GitHub Copilot (`.github/copilot-instructions.md`): - Single file, similar to CLAUDE.md but may use different heading conventions - Focus on coding patterns and conventions (Copilot is code-completion oriented) Windsurf (`.windsurf/rules/_ai-context.md`): - Create a summary context rule that points to existing rules and workflows - Do NOT duplicate content already in `.windsurf/rules/.md` - Focus on the docs map, workflow inventory, and skills inventory - Add conditional trigger: "When starting a new conversation or task" Cursor* (`.cursor/rules/_ai-context.mdc`): - Similar to Windsurf but uses MDC format with YAML frontmatter - Mirror the Windsurf content adapted to Cursor conventions ### 4. Present to User Show the generated config file to the user before writing it: - Highlight any sections that are thin or missing source material - Ask if any project-specific conventions should be added - Confirm file location is correct --- ## Deliverables - ✅ AI IDE config file generated for chosen target(s) - ✅ All 10 sections populated from source material - ✅ Agent test lanes + skills inventoried when SAO §17 applies - ✅ User reviewed the generated content - ✅ Ready to proceed to DSP-06 (Review & Commit) ## Artifacts Produced None ## Artifacts Consumed ESM Templates (inventoried for Section 7 — Artifact Templates): - User Journey Template (`ESM/artifacts/user_journey_template.md`) - IA Guidelines Template (`ESM/artifacts/ia_guidelines_template.md`) - Feature File Template (`ESM/artifacts/feature_file_template.feature`) DTA Templates: - System Architecture Overview Template (`DTA/artifacts/sao_document_template.md`) DSP Templates (used to generate the output config file in step 2): - CLAUDE.md Template (`DSP/artifacts/claude_md_template.md`) - Copilot Instructions Template (`DSP/artifacts/copilot_instructions_template.md`) - Windsurf/Cursor Rules Template (`DSP/artifacts/windsurf_cursor_rules_template.md`) BSP Templates (inventoried for Section 7): - Makefile Template (`BSP/artifacts/makefile_template.mk`) DCD Templates (inventoried for Section 7): - Helm Chart Template (`DCD/artifacts/` — reference structure) BPE Templates (inventoried for Section 7): - Implementation Plan Template (`BPE/artifacts/implementation_plan_template.md`) - Definition of Done Checklist Template (`BPE/artifacts/definition_of_done_checklist_template.md`) DCI Templates (inventoried for Section 7): - Infra Repo Scaffold (`DCI/artifacts/` — reference structure) ## Notes No additional notes.
#6	Review & Commit	Read the 'DSP-6 Review & Commit' activity from playbook 'Junior Edda' (workflow 'Deploy Software Process'). Follow its guidance when assisting me. # Review & Commit ## Objective Review the generated AI IDE configuration file(s) with the user, make any requested adjustments, and commit to the repository. --- ## Process ### 1. Present Generated Config for Review Show the user the generated file(s) from DSP-05: For each generated file, verify: \| Check \| Criteria \| \|-------\|----------\| \| Completeness \| All 10 sections present and populated \| \| Accuracy \| Architecture matches current SAO.md \| \| Docs Map \| All referenced files actually exist \| \| Workflows \| All available workflows listed \| \| Skills \| All available skills listed (or "none yet" noted) \| \| Artifact Templates \| All templates referenced with correct paths \| \| Conventions \| Coding standards match team practice \| \| Running Locally \| Commands are correct and tested \| ### 2. Collect User Feedback Ask the user: 1. Is anything missing? — project-specific conventions, team norms, special tools? 2. Is anything wrong? — outdated architecture, incorrect paths, stale conventions? 3. Is anything unnecessary? — sections that add noise without value? 4. Tone and style — too verbose? Too terse? Right level of detail? ### 3. Apply Adjustments Make requested changes to the generated file(s). Common adjustments: - Add project-specific environment variables or secrets handling - Add team-specific review processes - Adjust emphasis on certain workflows over others - Add links to external resources (CI/CD dashboards, design tools, etc.) ### 4. Validate File Locations Confirm files are in the correct locations: \| Target \| Expected Location \| Exists? \| \|--------\|-------------------\|---------\| \| Claude Code \| `CLAUDE.md` (project root) \| ✅/❌ \| \| GitHub Copilot \| `.github/copilot-instructions.md` \| ✅/❌ \| \| Windsurf \| `.windsurf/rules/_ai-context.md` \| ✅/❌ \| \| Cursor \| `.cursor/rules/_ai-context.mdc` \| ✅/❌ \| ### 5. Commit Commit the generated config file(s) with: ``` docs(dsp): generate AI IDE configuration for {target} - Generated {filename} from SAO.md, ESM artifacts, and workflow inventory - Includes: architecture, docs map, workflows, skills, artifact templates, AI/human collaboration patterns, coding conventions, BPE workflow reference - Target IDE: {Claude Code \| GitHub Copilot \| Windsurf \| Cursor} ``` --- ## Deliverables - ✅ Config file(s) reviewed by user - ✅ Adjustments applied per user feedback - ✅ File locations validated - ✅ Committed to repository - ✅ AI IDE configured — DSP is complete. ## Next Step If BSP (Bootstrap Project) is not yet complete: run BSP now. BSP creates the Makefile, installs dependencies, and stands up the welcome page — all required by PIN-01. If BSP is already complete: proceed to BSP-08 for the Construction Handoff and mode selection. Do not start BPE or PIN directly from DSP — the project must be bootstrapped first.
Estimate the Project
#1	Assess Estimation Readiness	Read the 'EST-1 Assess Estimation Readiness' activity from playbook 'Junior Edda' (workflow 'Estimate the Project'). Follow its guidance when assisting me. ## Purpose Determine what inputs are available, choose the appropriate estimation level (Level 1 SWAG vs. Level 2 Detailed), and produce an Estimation Strategy document that governs the rest of the workflow. ## Prerequisites - Project idea, vision document, or feature files exist - Stakeholder available to answer risk-profile questions ## Steps ### Step 1: Inventory Available Inputs Check which artifacts exist and record their status: \| Artifact \| Location \| Status \| \|---\|---\|---\| \| BDD Feature Files \| `docs/features/` \| exists / partial / missing \| \| Software Architecture Overview \| `docs/architecture/SAO.md` \| exists / missing \| \| User Journey \| `docs/features/user_journey.md` \| exists / missing \| \| Previous Sprint Actuals \| Reference Table \| exists / missing \| \| Reference Story Calibration \| Reference Table \| calibrated / uncalibrated \| ### Step 1.5: Check Project Bootstrap and Process Setup Status Verify whether the project has been bootstrapped (BSP workflow) and whether the AI IDE has been configured (DSP workflow): BSP check — is the project runnable? \| Check \| What to Look For \| Status \| \|-------\|------------------\|--------\| \| Git repository \| `.git/` directory exists \| exists / missing \| \| Project entry point \| `manage.py`, `package.json`, `Cargo.toml`, etc. \| exists / missing \| \| Dependency file \| `requirements.txt`, `package.json`, `Cargo.toml` \| exists / missing \| \| Makefile \| `Makefile` with `provision`, `run`, `test` targets \| exists / missing \| \| Source directories \| Application code directories per SAO.md structure \| exists / missing \| If 3+ BSP checks are missing → project is not bootstrapped. Action for non-bootstrapped projects: Ask user: "Project is not bootstrapped. Include BSP + DSP setup in the estimate as Sprint 0 overhead?" - Yes → Add Sprint 0 overhead to estimation: - Create a "Sprint 0: Project Setup" line item in the WBS and Client Quote - BSP overhead: 10 FP (8 activities — see REFERENCE_TABLE §7) - DSP overhead: 5 FP (6 activities — see REFERENCE_TABLE §7) - Total Sprint 0: ~15 FP (before Stack × Org adjustment) - Record in ESTIMATION_STRATEGY.md: "Sprint 0 bootstrap overhead included: 15 FP" - No → Redirect to BSP workflow: - Stop EST workflow - Direct user: "Please run BSP (Bootstrap Project) workflow first, then return to EST" - Record in ESTIMATION_STRATEGY.md: "Bootstrap deferred — not included in estimates" DSP check — is the AI IDE configured? \| Check \| What to Look For \| Status \| \|-------\|------------------\|--------\| \| CLAUDE.md \| `CLAUDE.md` exists in project root \| exists / missing \| \| Copilot instructions \| `.github/copilot-instructions.md` exists \| exists / missing \| \| Windsurf/Cursor rules \| `.windsurf/rules/` or `.cursor/rules/` exists \| exists / missing \| If DSP artifacts are missing and BSP is being quoted: include DSP FP in the Sprint 0 overhead (already in the 15 FP above). If BSP is done but DSP is missing: add DSP as a 5 FP line item in Sprint 1. If project is fully bootstrapped and DSP is done → proceed to Step 2 (no action needed). ### Step 2: Run Boehm & Turner 5-Factor Risk Assessment Rate each factor on the appropriate scale. Circle the home ground that applies. \| Factor \| Agile Home Ground \| Plan-Driven Home Ground \| This Project \| \|---\|---\|---\|---\| \| Team Size \| ≤10 \| ≥20 \| ___ \| \| Criticality \| Low (comfort) \| High (money/life) \| ___ \| \| Requirements Dynamism \| High change rate \| Stable \| ___ \| \| Culture \| Chaos-tolerant \| Order-preferring \| ___ \| \| Personnel \| All senior/CRACK \| Mixed skill levels \| ___ \| Identify dominant risk type: - A-risks dominate (too agile) → lean toward more process/Level 2 - P-risks dominate (too plan-driven) → stay Level 1, iterate fast - Mixed → Level 1 now, schedule Level 2 after Sprint 1 ### Step 3: Select Estimation Level Level 1 SWAG — use when: - Feature files exist but SAO.MD is absent - Project is in early discovery - Team size ≤ 5, low criticality - First sprint (always start here) Level 1 + Level 2 Detailed — use when: - `docs/architecture/SAO.md` exists and is current - Requirements stability ≥ 80% (McConnell prerequisite) - Team size > 10 or criticality is high - Stakeholder requires commitment-quality estimates Both levels produce the same Excel output; Level 2 simply populates additional tabs (WBS Features + Detailed Estimates) and enables the Client Quote tab (AFP pricing). ### Step 4: Document Estimation Strategy Create or update `docs/plans/ESTIMATION_STRATEGY.md` with: - Estimation level chosen and rationale - Risk profile summary (5-factor ratings) - Sprint 0 overhead included? (BSP/DSP FP count) - Gate condition for upgrading to Level 2 (e.g., "after SAO.MD is complete") - Sprint refinement cadence (default: every sprint close) - Reference Table location ### Step 5: Open Excel Estimation Template Open `docs/plans/ESTIMATION_TEMPLATE.xlsx`. Verify all tabs are present: 0. Client Quote 1. Setup 2. Scenario List 3. ECF 4. TCF 5. Rough Estimates 6. Monte Carlo 7. WBS Features 8. Detailed Estimates If file does not exist, copy from `forge/templates/ESTIMATION_TEMPLATE.xlsx`. ## Rules to Follow ### I. Prerequisites Before Estimating Never produce token or duration estimates without first completing Steps 1–3. An estimate produced without a risk assessment is a guess, not engineering. ### II. Level Decision is Reversible Choosing Level 1 does not prevent upgrading to Level 2 later. Record the upgrade gate condition explicitly so it is not forgotten. ### III. McConnell Prerequisite Checklist Before Level 2: confirm problem definition is documented, requirements are ≥ 80% complete, and architecture is sketched. Without these, Level 2 adds false precision, not real accuracy. ### IV. Sprint 0 Is Always Quoted Separately BSP and DSP overhead FP must appear as a separate line item on the Client Quote — never blended into feature delivery FPs. The client must see the setup cost explicitly. ## Success Criteria - Input inventory complete - Bootstrap and DSP status checked; Sprint 0 overhead FP recorded if applicable - 5-factor risk assessment documented - Estimation level selected with rationale - ESTIMATION_STRATEGY.md created/updated - Excel template open and verified
#2	Calibrate Reference Stories	Read the 'EST-2 Calibrate Reference Stories' activity from playbook 'Junior Edda' (workflow 'Estimate the Project'). Follow its guidance when assisting me. ## Purpose Define concrete reference stories at each T-shirt size, assign K-token baselines (tokens per story point) to anchor token budget estimates, and assign FP weights to anchor client-facing AFP pricing. This calibration baseline governs both internal estimates and client quotes for the entire project. ## Prerequisites - EST-01 complete - Reference Table accessible (or being created for first time) ## Steps ### Step 1: Define Reference Stories A reference story is a concrete, completed BDD scenario that the team agrees represents a given size. Every future scenario is sized relative to these anchors. Populate the Setup tab of ESTIMATION_TEMPLATE.xlsx with reference stories: \| Size \| SP (internal) \| FP weight (client) \| Example Reference Story \| K Tokens (min) \| K Tokens (exp) \| K Tokens (max) \| \|------\|:-------------:\|:------------------:\|-------------------------\|---------------:\|---------------:\|---------------:\| \| XS \| 0.5 \| 0.5 \| Read-only list view, no filtering, single model \| — \| — \| — \| \| S \| 1 \| 1 \| Single CRUD operation, one model, 3–5 scenarios \| — \| — \| — \| \| M \| 2 \| 2 \| Feature with 2 models, service layer, 6–10 scenarios \| — \| — \| — \| \| L \| 5 \| 3 \| Multi-model feature with integrations, 10–15 scenarios \| — \| — \| — \| \| XL \| 8 \| 5 \| Complex subsystem, external API, >15 scenarios \| — \| — \| — \| SP vs FP — keep them separate: - SP (Story Points) — internal effort measure. Used to compute token budget and duration. Never on client quote. - FP (Function Points) — client-facing deliverable measure. Used in AFP formula. Goes on the invoice. - L and XL FP weights are lower than SP because complex internal effort does not translate 1:1 to delivered client value. Reference stories must be real scenarios from either: - This project's own backlog (preferred once Sprint 1 completes) - The Reference Table from prior projects ### Step 2: Assign K-Token Baselines K tokens = total tokens (input + output) consumed by the AI to implement one story point, across all BPE activities for that scenario size. If Reference Table has prior data: - Copy K-token values (min/expected/max) per size tier from Reference Table §1 - Note the project and sprint they came from - Adjust if tech stack or AI model differs If no prior data (first project / calibration sprint): Use seed estimates from Reference Table §1: - XS (0.5 SP): min=12K, expected=22K, max=36K tokens - S (1 SP): min=25K, expected=45K, max=72K tokens - M (2 SP): min=60K, expected=100K, max=160K tokens - L (5 SP): min=155K, expected=250K, max=410K tokens - XL (8 SP): min=275K, expected=440K, max=720K tokens These are PERT seed values — mark as "uncalibrated" until Sprint 1 actuals are collected. ### Step 3: Document AI Productivity Adjustment Factor (PAF) Record in Setup tab: - AI Model in use (Claude Sonnet 4.x, GPT-4o, etc.) - PAF: 1.3–1.6× speed gain over traditional (per Peng et al. 2023, GitHub 2024) - Rework surcharge: +10–15% of coding tokens (41% higher churn rate, Ziegler 2024) - Net PAF applied: ___ ### Step 4: Define Sprint Parameters In Setup tab, record: - Sprint duration: ___ days (default: 1 day for AI-assisted development) - Working hours per day: ___ (default: 8h) - Token budget per sprint: ___ K (from stakeholder constraint or derived) - Max SP per sprint: ___ (from capacity) ### Step 5: Record Pricing Calibration Status In Setup tab, record: - $/FP rate: ___ (SEED default: $250 — see Reference Table §6) - Status: SEED / CALIBRATED (SEED until 3 sprints of actuals) - Stack Factor selected: ___ (from Reference Table §4 — applies to AFP) - Org Factor selected: ___ (from Reference Table §5 — applies to AFP) These inputs feed the Client Quote tab (Tab 0). ### Step 6: Flag Calibration Status Mark each K-token row in the Setup tab as one of: - CALIBRATED — based on ≥3 actual sprints for this size tier - SEED — using reference table baseline, not yet validated - BORROWED — from Reference Table of a different project Estimates from SEED or BORROWED sources carry wider PERT ranges. The Monte Carlo simulation will reflect this uncertainty. ## Rules to Follow ### I. Reference Stories Must Be Concrete Vague reference stories produce vague estimates. If no suitable reference story exists, the first sprint is a calibration sprint — its primary output is validated K-token values, not features. ### II. Never Flatten to Single-Point Estimates Always record min/expected/max. Single-point K-token values underestimate variance and defeat the purpose of Monte Carlo. ### III. SP and FP Are Different Units — Never Conflate SP measures effort. FP measures deliverable capability. Both are needed: SP drives internal token budget, FP drives the client quote. Record both in the Setup tab. ### IV. Calibration Improves Sprint-by-Sprint After each sprint close (EST-08), update K-token actuals and $/FP_actual. After 3+ sprints per size tier, mark as CALIBRATED and narrow the PERT range. ## Success Criteria - Reference stories defined for all active size tiers - Both SP and FP weight recorded per size tier - K-token baselines populated (SEED or CALIBRATED) with min/expected/max - AI productivity adjustment factor documented - Sprint parameters set - $/FP, Stack Factor, Org Factor recorded in Setup tab - Setup tab of ESTIMATION_TEMPLATE.xlsx complete ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - GitHub Release (Other, Optional) — produced by Close Iteration (#118). - Lessons Learned Document (Document, Optional) — produced by Close Iteration (#118).
#3	Size Scenarios (Level 1 SWAG)	Read the 'EST-3 Size Scenarios (Level 1 SWAG)' activity from playbook 'Junior Edda' (workflow 'Estimate the Project'). Follow its guidance when assisting me. ## Purpose Assign a T-shirt size (XS → XL) to every BDD scenario using the reference stories as anchors. Record both SP (for token budget) and FP weight (for client AFP). Produce story point totals per feature and per sprint. Populate the Scenario List tab of ESTIMATION_TEMPLATE.xlsx. ## Prerequisites - EST-02 complete (reference stories defined, K-token baselines set, SP and FP weights recorded) - BDD feature files exist in `docs/features/` ## Steps ### Step 1: Enumerate All Scenarios Read all `.feature` files in `docs/features/`. For each scenario, record: - Scenario ID (e.g., `FOB-PLAYBOOKS-LIST+FIND-01`) - Feature name - Act/group - One-line description (from Scenario title) Paste the list into the Scenario List tab, one row per scenario. ### Step 2: Size Each Scenario Against Reference Stories For each scenario, compare to the reference stories defined in EST-02: Sizing heuristics: \| Ask This \| Size \| SP \| FP \| \|----------\|------\|:--:\|:--:\| \| Single read-only view, no writes? \| XS \| 0.5 \| 0.5 \| \| One model, one CRUD operation, happy path? \| S \| 1 \| 1 \| \| Two models or one model with complex logic? \| M \| 2 \| 2 \| \| Multiple models, service layer, or external call? \| L \| 5 \| 3 \| \| Multi-subsystem, external API, complex orchestration? \| XL \| 8 \| 5 \| \| Clearly larger than XL? \| Split first \| — \| — \| For each scenario, record: assigned size, SP value, FP weight, and a one-line sizing rationale. Anti-patterns — never do these: \| Anti-pattern \| Why Wrong \| Correct Approach \| \|---\|---\|---\| \| Size by scenario count (10 scenarios → L or XL) \| Scenario count measures test breadth, not implementation effort \| Size by code complexity and reuse, not test count \| \| Size 2nd/3rd CRUD entity same as 1st \| Pattern reuse cuts effort 3–5× \| Downgrade reused entities: first entity S→M, 2nd+ XS→S \| \| Size all config/bootstrap steps as S or M \| Config-heavy work is code-light \| Config work is XS; infrastructure overhead goes in Sprint 0 \| \| Treat reuse as free \| EXTEND still consumes tokens to read/modify \| Apply 0.6× EXTEND multiplier in Level 2 (EST-06) \| ### Step 3: Challenge Outliers Before finalizing, review: - Any scenario sized XL → can it be split into two L scenarios? - Any scenario sized > XL → must be split (McConnell rule: no single unit > 1.5× reference L) - Any cluster of XS scenarios that share a model → consider whether they belong to one M Propose splits/merges to user for approval before proceeding. ### Step 4: Group by Feature and Sprint In the Scenario List tab: 1. Group rows by Feature (sub-total SP and FP per feature) 2. Assign scenarios to sprints based on: - Dependencies (parent model before child, auth before protected endpoints) - Priority (must-have before nice-to-have) - Sprint capacity (SP per sprint from Setup tab) 3. Record: Sprint #, SP allocated, FP allocated, cumulative SP, cumulative FP ### Step 5: Compute Totals In the Scenario List tab, compute and record: - Total scenarios: ___ - Total SP: ___ (drives token budget in EST-05) - Total FP: ___ (drives AFP quote in Client Quote tab) - SP per sprint (sum per sprint column) - FP per sprint (sum per sprint column) - Estimated number of sprints ### Step 6: Flag Assumptions For any scenario where sizing is uncertain, add a flag column entry: - `ASSUMPTION: sized M because requirements unclear for error handling` - `ASSUMPTION: sized L but may be M if third-party API has SDK` These assumptions become the first risk items to address in Sprint 1. ## Rules to Follow ### I. Size Relative to Reference, Not Absolute Never size in hours or days. Size by comparing to the reference story. The reference story is the unit of measure. ### II. One Scenario Per Row Do not aggregate scenarios into epics in this tab. The Monte Carlo simulation operates at the scenario level. Aggregation happens only in the sprint grouping columns. ### III. Record Both SP and FP Every row must have both SP (for internal token budget) and FP weight (for client quote). They differ for L and XL — do not conflate them. ### IV. Scenario Must Be Independently Executable If a scenario cannot be tested in isolation, split it or make the dependency explicit. ### V. No Hidden Work Every piece of work that will consume tokens must map to a scenario. Infrastructure, CI/CD, devops scaffolding → Sprint 0 overhead line item (BSP/DSP FPs from EST-01). ## Success Criteria - All BDD scenarios enumerated and sized - Both SP and FP weight recorded per scenario - No unresolved XL+ scenarios (all split or explicitly approved) - Scenarios grouped into sprints respecting dependencies and capacity - SP and FP totals computed per feature, per sprint, project total - Assumptions flagged - Scenario List tab of ESTIMATION_TEMPLATE.xlsx complete
#4	Assess Risk Multipliers	Read the 'EST-4 Assess Risk Multipliers' activity from playbook 'Junior Edda' (workflow 'Estimate the Project'). Follow its guidance when assisting me. ## Purpose Two separate multiplier assessments are performed here: Section A — Internal (ECF/TCF): Rate Environmental and Technical Complexity Factors to produce the combined multiplier that adjusts raw SP-based token estimates. These factors also calibrate the $/FP rate. Never shown to client. Section B — Client-Facing (Stack Factor / Org Factor): Select the Stack Factor and Org Factor that go into the AFP formula on the Client Quote. These encode the same real-world friction in commercially legible terms. Shown on quote. The two assessments are done together because they are informed by the same project context, but they produce separate outputs. ## Prerequisites - EST-03 complete (scenarios sized) - Stakeholder available to validate risk ratings --- ## Section A — Internal: ECF / TCF ### Step A1: Rate ECF Factors Open the ECF tab in ESTIMATION_TEMPLATE.xlsx. Rate each factor from 0 (no influence) to 5 (strong influence). Environmental Complexity Factors: \| # \| Factor \| Weight \| Rating (0–5) \| Weighted \| \|---\|---\|---\|---\|---\| \| E1 \| Familiarity with the AI model/tooling used \| 1.5 \| \| \| \| E2 \| Part-time participation (interruptions, context switching) \| -1.0 \| \| \| \| E3 \| Analyst / prompt engineering experience \| 0.5 \| \| \| \| E4 \| Lead developer application experience \| 0.5 \| \| \| \| E5 \| Motivation of team \| 1.0 \| \| \| \| E6 \| Stability of requirements \| 2.0 \| \| \| \| E7 \| Part-time users / product owners \| -1.0 \| \| \| \| E8 \| Difficulty of programming language / stack \| -1.0 \| \| \| ECF Formula: `ECF = 1.4 + (-0.03 × Σ(Weight × Rating))` A value < 1.0 means favorable environment (fewer tokens). A value > 1.0 means challenging (more tokens). AI-Specific Extension (add to ECF tab): \| # \| Factor \| Weight \| Rating (0–5) \| Weighted \| \|---\|---\|---\|---\|---\| \| A1 \| AI model tier (Claude Opus=5, Sonnet=3, Haiku=1) \| 0.8 \| \| \| \| A2 \| Prompt maturity (mature prompts=5, first use=1) \| 0.6 \| \| \| \| A3 \| Hallucination risk (well-known domain=1, novel=5) \| -0.5 \| \| \| \| A4 \| Context window pressure (small ctx=5, large=1) \| -0.4 \| \| \| \| A5 \| AI-generated code rework rate (41% baseline = 3) \| -0.6 \| \| \| `ECF_final = ECF_base × (1 + AI_adjustment)` ### Step A2: Rate TCF Factors Open the TCF tab. Rate each factor 0–5. Technical Complexity Factors: \| # \| Factor \| Weight \| Rating (0–5) \| Weighted \| \|---\|---\|---\|---\|---\| \| T1 \| Distributed system / microservices \| 2.0 \| \| \| \| T2 \| Response time / performance requirements \| 1.0 \| \| \| \| T3 \| End-user efficiency (optimized UX needed) \| 1.0 \| \| \| \| T4 \| Complex internal processing / algorithms \| 1.0 \| \| \| \| T5 \| Code reusability requirement \| 1.0 \| \| \| \| T6 \| Easy to install / deploy \| 0.5 \| \| \| \| T7 \| Easy to use (usability) \| 0.5 \| \| \| \| T8 \| Portability across platforms \| 2.0 \| \| \| \| T9 \| Easy to change / maintainability \| 1.0 \| \| \| \| T10 \| Concurrent use / multi-user \| 1.0 \| \| \| \| T11 \| Security features \| 1.0 \| \| \| \| T12 \| Direct access for third parties / APIs \| 1.0 \| \| \| \| T13 \| Special user training required \| 1.0 \| \| \| TCF Formula: `TCF = 0.6 + (0.01 × Σ(Weight × Rating))` ### Step A3: Compute Internal Combined Multiplier `Internal Multiplier = ECF_final × TCF` Record in Setup tab. Applied to all SP × K estimates in EST-05 to produce the token budget. This multiplier also feeds the $/FP calibration rate (EST-08): as ECF/TCF are refined by actuals, the effective cost per FP delivered changes, and $/FP is updated accordingly. \| Combined Multiplier \| Meaning \| \|---\|---\| \| < 0.8 \| Highly favorable — experienced team, stable requirements, mature AI tooling \| \| 0.8 – 1.0 \| Normal — typical project \| \| 1.0 – 1.3 \| Moderate risk — some unknowns \| \| 1.3 – 1.6 \| High risk — unstable requirements or novel domain \| \| > 1.6 \| Very high risk — reconsider scope before estimating further \| --- ## Section B — Client-Facing: Stack Factor and Org Factor ### Step B1: Select Stack Factor From Reference Table §4, select the base tier that best describes the client's technology environment, then apply any additive modifiers: Base tiers: \| Stack Factor \| Select If... \| \|:------------:\|-------------\| \| 0.85 \| Greenfield, single clean modern stack, no legacy \| \| 1.00 \| Standard single stack (Django+HTMX, Rails, Node, FastAPI) \| \| 1.25 \| Two integrated stacks (React SPA + REST backend) \| \| 1.50 \| Legacy codebase integration required \| \| 1.75 \| Multi-cloud or platform-constrained \| \| 2.00 \| Enterprise platform (Salesforce, SAP, ServiceNow) \| \| 2.50+ \| Government / highly regulated (FedRAMP, ITAR) \| Additive modifiers: on-premises +0.10, legacy integration +0.15, multi-cloud +0.15, real-time +0.10, mobile +0.20. Record: Stack Factor base + modifiers = Stack Factor total: ___ ### Step B2: Select Org Factor From Reference Table §5, select the tier that best describes the client's organizational friction: \| Org Factor \| Select If... \| \|:----------:\|-------------\| \| 0.80 \| Startup — flat structure, one decision-maker, no formal process \| \| 1.00 \| Small team / SME — basic sprints, PM involved \| \| 1.25 \| Mid-size — defined SDLC, multiple stakeholders \| \| 1.50 \| Enterprise — formal change management, legal/security review gates \| \| 2.00 \| ITIL/ITSM — CAB approvals, change freeze windows \| \| 2.50 \| Regulated enterprise — SOX, PCI-DSS, HIPAA sign-off gates \| \| 3.50 \| Government — procurement gates, FISMA/FedRAMP, multi-agency review \| Record: Org Factor: ___ ### Step B3: Confirm $/FP Rate From Setup tab (populated in EST-02), confirm the $/FP rate applies: - SEED: $250/FP (default until 3 sprints calibrated) - CALIBRATED: actual $/FP from last sprint close (EST-08) Record in Client Quote tab (Tab 0). ### Step B4: Preview AFP With Stack Factor, Org Factor, and total FP from Scenario List, compute preview AFP: ``` Preview AFP = Total FP (from Scenario List) × Stack Factor × Org Factor Preview Quote Total = Preview AFP × $/FP ``` This is a preview — the AFP on the Client Quote tab will use the final FP total from EST-05/EST-06. Present preview to user for a sanity check before proceeding. --- ## Rules to Follow ### I. Rate ECF/TCF Honestly, Not Optimistically Optimistic risk ratings are the most common estimation failure. If in doubt between 3 and 4, choose 4. ### II. ECF/TCF Are Internal — Never on Client Quote The client sees Stack Factor and Org Factor. ECF/TCF are calibration inputs for $/FP. Mixing them up produces misleading quotes. ### III. Re-Rate Each Sprint ECF/TCF are not static. At each sprint close (EST-08), revisit factors that have changed. Stack Factor and Org Factor can also change if the project context changes — update and re-quote. ### IV. If AFP Preview Looks Wrong, Fix the Inputs — Not the Rate If the preview AFP produces a surprising total, diagnose which input is off (FP count? Stack Factor? Org Factor?) — not pad or cut the $/FP rate to hit a target number. ## Success Criteria - ECF and TCF factors rated with rationale for outliers (Section A) - Internal combined multiplier computed and recorded in Setup tab - Stack Factor and Org Factor selected and recorded (Section B) - $/FP rate confirmed - AFP preview computed and reviewed - ECF, TCF tabs and Client Quote tab of ESTIMATION_TEMPLATE.xlsx updated
#5	Produce Rough Estimates + AFP	Read the 'EST-5 Produce Rough Estimates + AFP' activity from playbook 'Junior Edda' (workflow 'Estimate the Project'). Follow its guidance when assisting me. ## Purpose Produce two parallel outputs from the Level 1 sizing: 1. Internal token budget — SP × K-token baselines × ECF × TCF → token estimates per sprint and project total. Used for sprint planning and AI cost forecasting. 2. AFP (Adjusted Function Points) — Σ FP × Stack Factor × Org Factor → the client-facing deliverable measure that feeds the quote. Populated in the Client Quote tab. Both outputs come from the same Level 1 sizing. Token budget stays internal; AFP goes on the invoice. ## Prerequisites - EST-03 complete (SP and FP totals per sprint in Scenario List) - EST-04 complete (internal multiplier in Setup tab; Stack Factor + Org Factor in Client Quote tab) - K-token baselines in Setup tab (SEED or CALIBRATED) ## Steps ### Step 1: Compute Internal Token Estimates Per Scenario For each scenario in the Scenario List tab, compute using SP: ``` Raw Tokens (min) = SP × K_min Raw Tokens (expected) = SP × K_expected Raw Tokens (max) = SP × K_max ``` Where K values are the K-token-per-SP baselines from the Setup tab for the assigned size tier. ### Step 2: Apply Internal Risk Multiplier ``` Adjusted Tokens (min) = Raw Tokens (min) × Internal Multiplier × 0.85 Adjusted Tokens (expected) = Raw Tokens (expected) × Internal Multiplier Adjusted Tokens (max) = Raw Tokens (max) × Internal Multiplier × 1.15 ``` The 0.85/1.15 asymmetric adjustment preserves PERT shape after multiplier application. ### Step 3: Aggregate Token Budget to Sprint Level In the Rough Estimates tab, for each sprint: - Sum adjusted token estimates (min/expected/max) across all scenarios in that sprint - Record sprint token budget (expected) - Record sprint token range (min → max) ### Step 4: Derive Duration ``` Duration (days) = Sprint Token Budget (expected) / Daily Token Throughput ``` Where Daily Token Throughput = tokens the AI processes per working day (from Setup tab, typically 500K–2M depending on model and workflow). For the project total, also compute with McConnell's schedule formula: ``` Duration (days) = 3.0 × (Total Effort Person-Months)^(1/3) ``` (For solo AI development, use sprint-by-sprint approach instead.) ### Step 5: Apply COCOMO Convergence Ranges Adjust estimate ranges according to current phase: \| Phase \| Min Multiplier \| Max Multiplier \| \|---\|---\|---\| \| Initial Concept (vision only) \| × 0.25 \| × 4.0 \| \| Approved Concept (scenarios exist) \| × 0.5 \| × 2.0 \| \| Requirements Spec (≥80% complete) \| × 0.67 \| × 1.5 \| \| Architecture (SAO.MD complete) \| × 0.80 \| × 1.25 \| Mark which phase applies. ### Step 6: Compute AFP (Client-Facing) In the Client Quote tab, compute AFP using FP weights (not SP): ``` AFP = Σ FP × Stack Factor × Org Factor ``` Where: - Σ FP = total FP from Scenario List tab (feature delivery FPs only) - Stack Factor = from EST-04 Section B (Reference Table §4) - Org Factor = from EST-04 Section B (Reference Table §5) Add Sprint 0 overhead separately: ``` Sprint 0 AFP = BSP+DSP FP × Stack Factor × Org Factor = 15 FP × Stack × Org (if bootstrap included) ``` Compute total quote: ``` Quote Total = (Feature AFP + Sprint 0 AFP) × $/FP ``` ### Step 7: Populate Rough Estimates Tab For each sprint, record: - Sprint #, scenarios included, SP total, FP total - Token budget: min / expected / max (in K tokens) — internal - Duration: min / expected / max (in days) — internal - Phase (convergence range applied) - Status: SEED / CALIBRATED / BORROWED For project total: total token budget, total duration, number of sprints, estimated completion date range. ### Step 8: Prepare Two Summaries Internal summary (for sprint planning): ``` Token Budget: P50 = ___ K tokens (range: ___ to ___) Duration: ___ sprints / ___ days (range: ___ to ___) Calibration: {SEED / CALIBRATED} ``` Client summary (for quote communication): ``` Feature delivery: ___ FP → AFP = ___ → $___ Sprint 0 setup: 15 FP → AFP = ___ → $___ ───────────────────────────────────────────── Total AFP: ___ Total Quote: $___ Stack Factor: ___ Org Factor: ___ $/FP: $___ ``` Present both to user for review. ## Rules to Follow ### I. Always Show Ranges for Token Budget Never present a single-point token estimate. Always present min/expected/max. ### II. AFP Is the Client Unit — Token Budget Is Not The client receives AFP and the $ total. The token budget is an internal planning tool. Do not show K-token numbers in the client summary. ### III. Token Budget Is a Constraint, Not Just an Output If expected token budget exceeds the team's capacity, that is a scope/priority conversation. ### IV. AFP Drives Billing — SP Does Not Billing is always AFP × $/FP. Never invoice on SP or raw tokens. ### V. Label the Convergence Phase Every token estimate must declare its convergence phase. An "initial concept" estimate with ±400% uncertainty is not a commitment. ## Success Criteria - Token estimates (min/expected/max) computed for all scenarios (internal) - AFP computed from FP × Stack Factor × Org Factor (client-facing) - Sprint 0 overhead AFP included if bootstrap was flagged in EST-01 - Quote Total = AFP × $/FP computed - COCOMO convergence phase labeled - Rough Estimates tab and Client Quote tab of ESTIMATION_TEMPLATE.xlsx complete - Internal summary and client summary prepared and reviewed ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - Estimation Reference Table (Document, Required) — produced by Calibrate Reference Stories (#67). - Estimation Template (Excel) (Document, Required) — produced by Size Scenarios (Level 1 SWAG) (#68). - Lessons Learned Document (Document, Optional) — produced by Close Iteration (#118).
#6	Decompose Work Packages (Level 2)	Read the 'EST-6 Decompose Work Packages (Level 2)' activity from playbook 'Junior Edda' (workflow 'Estimate the Project'). Follow its guidance when assisting me. ## Purpose At Level 1 (EST-03) you sized features by T-shirt. That was good enough for a rough cut. Level 2 is different: you have the scenario, you have the screen, you have SAO.md describing exactly how the stack works. You don't need to guess which layers a feature touches — BPE-01 will tell you. EST-06 runs BPE-01 in dry-run/estimation mode on each work package to produce a bottom-up artifact list, then wraps each artifact with a PERT triplet from the Reference Table. This is the key idea: BPE-01 Plan → exact artifact list → PERT triplets per artifact → sum = Function Point decomposition. No generic taxonomy lookup required. ## Prerequisites - `docs/architecture/SAO.md` exists and is current - EST-05 complete (Rough Estimates available as cross-check) - Requirements stability ≥ 80% (McConnell prerequisite) ## Gating Condition If SAO.MD does not exist, skip this activity. Return here after SAO.MD is produced (typically after ESM workflow completes). Record this as a gate condition in ESTIMATION_STRATEGY.md. ## Steps ### Step 1: Select the Work Package Take the next undecomposed work package from the sprint plan (EST-05 output). You need three inputs: 1. The scenario file — `docs/features/{act}/{feature}.feature` 2. The screen — find the matching node in the dialogue map (`docs/architecture/screen-flow.drawio`) 3. SAO.md — the authoritative architecture and stack description ### Step 2: Run BPE-01 in Estimation Mode Execute BPE-01 (Plan Feature) for this work package, treating it as if starting from scratch. BPE-01 will produce an Implementation Plan that lists every artifact needed: ``` → Input: feature file + screen name + SAO.md → Output: Implementation Plan listing every artifact: - Django Model + Admin (if new data shape) - Repository methods (which ones, for what queries) - Service layer (what business logic) - Django View + URL pattern (which views, GET/POST) - Unit + Integration tests (what to test) - Django Template + HTMX (which fragments/pages) - Feature Acceptance Tests (from scenario steps) - Journey Certification Tests (if cross-feature flow) - DoD checklist - E2E Playwright tests + PR ``` For each artifact, BPE-01 will also output its reuse flag based on codebase assessment: - NEW — doesn't exist yet, build from scratch - EXTEND — exists but needs significant modification - REUSE — exists, minimal touch needed > Estimation mode means: produce the plan but do not write any code. Stop after BPE-01 Plan and record the artifact list. ### Step 3: Assign PERT Triplets For each artifact in the Implementation Plan, assign PERT triplets (min / expected / max tokens) from the Reference Table K ranges: \| 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 \| \| \| \| Template partials (reusable) \| 4 / 8 / 15 \| \| \| \| Feature Acceptance Tests \| 8 / 15 / 28 \| \| \| \| Journey Certification Tests \| 5 / 10 / 18 \| \| \| \| DoD checklist \| 3 / 6 / 12 \| \| \| \| E2E Playwright tests + PR \| 6 / 12 / 22 \| \| \| \| Implementation Plan (BPE-01) \| 5 / 8 / 15 \| \| \| Apply reuse multipliers based on BPE-01 codebase assessment: - NEW: 1.0× (full token range) - EXTEND: 0.6× (reading + modifying existing code) - REUSE: 0.3× (trivial wiring or config change) ### Step 4: Record the Work Package Enter in the WBS Features tab: ``` Scenario ID: {ACT}-{ENTITY}-{OPERATION}-{NN} Feature: {Feature name from .feature file} Screen: {Screen name from dialogue map} Sprint: {Sprint number} L1 Size: M (2 SP) BPE-01 run: YES / ESTIMATION MODE Artifacts from BPE-01 Plan: WP-01 Django Model (Widget) NEW min=12K exp=16K max=25K WP-02 Repository (WidgetRepo) NEW min=8K exp=11K max=18K WP-03 Service (WidgetService) EXTEND min=8K exp=11K max=19K [×0.6] WP-04 View + URL NEW min=10K exp=14K max=22K WP-05 Unit + Integration Tests NEW min=16K exp=22K max=38K WP-06 Template + HTMX REUSE min=2K exp=4K max=8K [×0.3] WP-07 Feature Acceptance Test NEW min=10K exp=14K max=22K WP-08 DoD checklist NEW min=4K exp=6K max=10K WP-09 E2E test + PR NEW min=8K exp=11K max=18K ──────────────────────────────────────────────────────────────────────── TOTAL: min=78K exp=109K max=180K ``` ### Step 5: Cross-Check Against Level 1 Rough Estimate Compare Level 2 total to Level 1 estimate from EST-05: - Within ±30% → consistent, proceed - L2 > 30% higher than L1 → which artifact is driving the gap? Document it. - L2 > 30% lower than L1 → check for missing artifacts. Common omissions: tests, DoD, E2E. Record delta and rationale in the WBS Features tab notes column. ### Step 6: Repeat for All Work Packages Work through all sprint work packages, highest priority first. After every sprint's worth, sum L2 totals and compare against the Monte Carlo seed in EST-07. If cumulative L2 is >25% outside L1 project total, update the Rough Estimates tab before proceeding. ## Rules to Follow ### I. BPE-01 Is the Decomposition Engine Do not substitute a generic artifact checklist for BPE-01 Plan. The whole point of Level 2 is that you have the actual feature, screen, and architecture — use them. BPE-01 will produce a more accurate artifact list than any template can. ### II. DoD Is Fixed Overhead The DoD checklist (BPE-06) applies to every work package. Never omit it. It is not optional. ### III. Tests Are Not Optional Unit, integration, feature acceptance, and E2E tests are separate work packages. Omitting them produces a false low — the work still happens, it just becomes unplanned rework. ### IV. Decompose Before Estimating Assigning a PERT triplet to a scenario as a whole without running BPE-01 first is a Level 1 estimate masquerading as Level 2. If you skip the BPE-01 step, mark confidence as LOW and document why. ### V. Reuse Is Not Free Extending an existing component still consumes tokens for reading, understanding, and modifying existing code. Use 0.3× for trivial reuse, 0.6× for significant extension, 1.0× for new. ## Success Criteria - BPE-01 Plan executed (estimation mode) for every Level 2 work package - Each work package has a full artifact list with reuse flags - PERT triplets assigned to every artifact - L1/L2 cross-check performed and delta documented - WBS Features and Detailed Estimates tabs complete ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - User Journey (Document, Required) — produced by Define User Journey (#36). - Screen Flow / Dialogue Map (Diagram, Required) — produced by Create Dialogue Maps (#38). - Feature Files (Document, Required) — produced by Write Feature Files (#39). - HTML Mockups (Code, Optional) — produced by Create Mockups (#40). - Estimation Reference Table (Document, Required) — produced by Calibrate Reference Stories (#67). - Estimation Template (Excel) (Document, Required) — produced by Size Scenarios (Level 1 SWAG) (#68).
#7	Run Monte Carlo Simulation	Read the 'EST-7 Run Monte Carlo Simulation' activity from playbook 'Junior Edda' (workflow 'Estimate the Project'). Follow its guidance when assisting me. ## Purpose Execute Monte Carlo simulation (10,000 iterations, triangular distributions) over the scenario-level PERT triplets to produce probabilistic delivery forecasts. The simulation produces two types of output: - Internal: P50/P80/P95 for token budget and calendar duration. Used for sprint planning and AI cost control. - Client-facing: P50/P80/P95 expressed in AFP and $ (AFP × $/FP). Used for delivery commitment communication. The EBS (Evidence-Based Scheduling) diagrams remain internal — the client quote shows AFP bands, not token S-curves. ## Prerequisites - EST-05 complete (Rough Estimates tab with min/expected/max per scenario and per sprint; AFP in Client Quote tab) - OR EST-06 complete for Level 2 (WBS with work-package-level PERT triplets) - Monte Carlo VBS script present in the Monte Carlo tab of ESTIMATION_TEMPLATE.xlsx ## Steps ### Step 1: Verify Simulation Inputs Before running, confirm in the Monte Carlo tab: - Each scenario row has: scenario ID, sprint, min tokens, expected tokens, max tokens - Sprint dependency order is correct - Internal combined multiplier from Setup tab is referenced - Daily throughput (tokens/day) is set in Setup tab If using Level 2 data from EST-06, aggregate work-package PERT triplets to scenario level first (sum of WP min → scenario min, etc.). ### Step 2: Run the VBS Simulation In the Monte Carlo tab, run the VBS macro (Alt+F8 → RunMonteCarloSimulation): The macro performs 10,000 iterations. In each iteration: 1. For every scenario, draw a random token sample from Triangular(min, expected, max) 2. Apply sprint dependency graph (sequential unless flagged parallelizable) 3. Compute total tokens for the iteration 4. Compute total duration (tokens / daily throughput, respecting sprint boundaries) 5. Record [total_tokens, total_duration] to results array Output columns populated by macro: - Column A: iteration token totals (sorted ascending) - Column B: iteration duration totals (sorted ascending) - Column C: cumulative probability (0.0 → 1.0) ### Step 3: Read Internal Simulation Results (Token Budget + Duration) \| Percentile \| Meaning \| Token Budget (K) \| Duration (days) \| \|---\|---\|---\|---\| \| P10 \| Only 10% chance of finishing within this \| ___ K \| ___ days \| \| P50 \| Median — 50/50 chance \| ___ K \| ___ days \| \| P80 \| 80% confidence — recommended for planning \| ___ K \| ___ days \| \| P95 \| Conservative commitment \| ___ K \| ___ days \| Recommended internal planning budget: P80 (ACM SAC 2021 — Monte Carlo achieves MMRE 20% vs 134% for developer estimates; P80 absorbs most residual error). Record these values in the Monte Carlo tab summary section. These are internal and inform sprint budget allocation. ### Step 4: Convert to AFP Bands (Client-Facing) Using AFP and $/FP from the Client Quote tab, compute AFP-equivalent ranges: ``` AFP_P50 = Feature AFP (baseline from EST-05) AFP_P80 = AFP_P50 × (P80_tokens / P50_tokens) ← scale AFP by same ratio as token bands AFP_P95 = AFP_P50 × (P95_tokens / P50_tokens) ``` Then compute $ ranges: ``` Quote_P50 = AFP_P50 × $/FP Quote_P80 = AFP_P80 × $/FP Quote_P95 = AFP_P95 × $/FP ``` Record in the Client Quote tab. This gives the client a defensible range without exposing tokens. ### Step 5: Produce EBS Diagrams (Internal) The EBS (Evidence-Based Scheduling) diagrams show cumulative probability curves — internal planning tools: Curve 1: Token Budget Certainty - X-axis: token budget (K tokens) from P10 to P95 - Y-axis: probability of completing within that budget (0% → 100%) - Mark calibration points: P50, P80, P95 Curve 2: Duration Certainty - X-axis: calendar date (from today to P95 completion date) - Y-axis: probability of completing by that date (0% → 100%) - Mark specific dates: P10, P50 (expected), P80 (planning), P95 (conservative) Both curves are generated by the VBS macro and embedded in the Monte Carlo tab. ### Step 6: Prepare Client Delivery Commitment From the AFP band computation: ``` Delivery Commitment — {Project Name} — {Date} Scope: {N} features, {total FP} FP, Sprint 0 setup included AFP (Adjusted Function Points): P50 (median): AFP = ___ → $___ P80 (planning): AFP = ___ → $___ ← recommended commitment P95 (committed): AFP = ___ → $___ Duration: P50 (median): ___ working days (by ___ date) P80 (planning): ___ working days (by ___ date) P95 (committed): ___ working days (by ___ date) Stack Factor: ___ Org Factor: ___ $/FP: $___ (SEED/CALIBRATED) ``` ### Step 7: Document Simulation Snapshot Save `docs/plans/MC_SNAPSHOT_{DATE}.md` with: - Date, input (total scenarios, total SP, total FP, convergence phase) - ECF/TCF combined multiplier, K-token calibration status - P50/P80/P95 internal (tokens + duration) - P50/P80/P95 client (AFP + $) - Sprint plan summary ## Rules to Follow ### I. Simulation Requires Min ≠ Max If any scenario has min = expected = max, expand: min = expected × 0.7, max = expected × 1.5. ### II. P80 Is the Planning Commitment Never commit to P50. P50 means 50% chance of missing. P80 is the minimum defensible planning target. ### III. Client Sees AFP Bands — Not Token Curves The EBS S-curve is an internal tool. The client communication uses AFP ranges and $ totals. ### IV. Simulate After Each Sprint Close Re-run EST-07 after each EST-08. The simulation updates with actuals replacing estimates for completed scenarios. ### V. Token Cost Is Computable but Internal Tokens × API rate = internal cost of delivery. This informs margin analysis and $/FP calibration. It is never on the client quote. ## Success Criteria - VBS simulation executed (10,000 iterations) - P10/P50/P80/P95 extracted for token budget and duration (internal) - AFP band and $ range computed for P50/P80/P95 (client-facing) - EBS diagrams generated (internal — Monte Carlo tab) - Client delivery commitment prepared (AFP + $ ranges) - MC_SNAPSHOT saved to `docs/plans/` - Monte Carlo tab and Client Quote tab updated
#8	Sprint Close & Rebaseline	Read the 'EST-8 Sprint Close & Rebaseline' activity from playbook 'Junior Edda' (workflow 'Estimate the Project'). Follow its guidance when assisting me. ## Purpose At the end of each sprint, collect actual token consumption, compute Velocity Factor (VF = actual FP delivered / estimated AFP), update K-token baselines, calibrate $/FP from actuals, and re-run Monte Carlo. This loop is the engine of estimate improvement and pricing calibration across the project. If scope changed during the sprint (requirements modified, feature added/removed): run BPE-08 (Process Change Request) first. Do not blend scope-change overruns into calibration data. ## Prerequisites - Sprint completed (or partially completed with clear scope boundary) - Token consumption data available from AI model billing/usage logs - Scenario completion status recorded - No unresolved scope changes (BPE-08 completed if needed) ## Steps ### Step 1: Collect Sprint Actuals For each scenario attempted in the sprint, record: - Scenario ID - Planned SP, planned FP weight - Planned tokens (expected from estimate) - Actual tokens consumed (from AI usage logs) - Actual API cost ($) for this sprint - Status: DONE / PARTIAL / BLOCKED / DEFERRED - Notes (scope changes, surprises — flag any BPE-08 items) Record in the Scenario List tab, "Sprint N Actuals" columns. ### Step 2: Compute Velocity Factor (Internal — Token-Based) For each completed scenario: ``` Token VF = Actual Tokens / Estimated Tokens (expected) ``` Sprint-level VF: ``` Sprint Token VF = Σ Actual Tokens (completed) / Σ Estimated Tokens (same scenarios) ``` \| VF Range \| Meaning \| Action \| \|---\|---\|---\| \| < 0.8 \| AI performed faster than estimated \| Reduce K_expected; tighten K_min \| \| 0.8 – 1.2 \| On target \| Minor adjustment only \| \| 1.2 – 1.5 \| Slower than expected \| Increase K_expected; widen K_max \| \| > 1.5 \| Significant overrun \| Investigate root cause before adjusting \| ### Step 3: Update K-Token Baselines For each size tier with ≥ 1 completed actual: 1. Append actual to running history in Reference Table §11 2. Recompute: K_expected = weighted average last 3–5 actuals; K_min = 10th pct; K_max = 90th pct 3. Update Setup tab K values 4. Calibration status: 1 actual → SEED; 2 actuals → BORROWED; ≥3 actuals → CALIBRATED ### Step 4: Calibrate $/FP (Client Pricing — Critical) Compute the actual cost per delivered FP for this sprint: ``` $/FP_actual_sprint = Actual API Cost ($) / Σ FP (completed scenarios) ``` Update the running $/FP calibration in Setup tab: ``` $/FP_calibrated = weighted average of $/FP_actual across last 3–5 sprints ``` Update $/FP in Client Quote tab with the calibrated rate. Change calibration status from SEED → CALIBRATED once 3+ sprint actuals are available. This is the feedback loop that keeps the AFP pricing model honest: as the team gets faster (PAF improves), $/FP drops; as scope grows harder, $/FP rises. The client quote rate tracks reality, not seed assumptions. ### Step 5: Compute AFP VF (Client-Facing — Delivery Performance) ``` AFP VF = Σ FP (delivered this sprint) / AFP (estimated for this sprint in Client Quote) ``` \| AFP VF \| Meaning \| \|---\|---\| \| > 1.0 \| Delivered more FP value than quoted — favorable \| \| = 1.0 \| On target \| \| < 1.0 \| Delivered less FP value than quoted — investigate \| Record AFP VF in Reference Table sprint actuals section. This is the metric to show the client as a delivery health indicator. ### Step 6: Re-Rate ECF/TCF (If Warranted) Review factors that may have changed: - E6 (requirements stability) — did requirements churn this sprint? - A3 (hallucination risk) — did AI quality improve as it learned the codebase? - A2 (prompt maturity) — did new prompts prove more efficient? Update ECF/TCF tabs if any factor changes by ≥ 1 point. Recompute internal combined multiplier. ### Step 7: Update Remaining Scenario Estimates For remaining (not yet started) scenarios: - Apply updated K baselines (token budget) - If a class of scenarios ran significantly over/under, apply Token VF as correction factor - Do not touch FP weights — FP is a client commitment, not an internal variable ### Step 8: Re-Run Monte Carlo Run EST-07 over remaining scenarios only: - Completed scenarios: replace with actuals (fixed values, no simulation) - Remaining scenarios: re-simulate with updated PERT distributions - Output: new P50/P80/P95 for token budget, duration, AFP, and $ Compare to previous MC_SNAPSHOT: - Is P80 completion date improving sprint-over-sprint? (healthy) - Is P80 drifting outward? (scope growth or systematic under-estimation — investigate) Save new `docs/plans/MC_SNAPSHOT_{DATE}.md`. ### Step 9: Update Reference Table Append to `docs/plans/REFERENCE_TABLE.md` §11: ``` ## Sprint {N} Actuals — {Date} \| Scenario \| Size \| SP \| FP \| Est. Tokens \| Actual Tokens \| Token VF \| Est. AFP \| Actual FP \| AFP VF \| \|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\| \| FOB-X-Y-01 \| M \| 2 \| 2 \| 110K \| 127K \| 1.15 \| 2 AFP \| 2 FP \| 1.0 \| $/FP this sprint: $___ (API cost $___ / ___ FP delivered) $/FP calibrated: $___ (was: $___) — status: SEED / CALIBRATED Updated K baselines: {list tiers updated} Combined multiplier: {value} (was: {previous}) ``` ### Step 10: Publish Sprint Report ``` Sprint {N} Estimation Report — {Date} Completed: {N} scenarios ({SP} SP / {FP} FP), {actual K}K tokens Planned: {N} scenarios ({SP} SP / {FP} FP), {planned K}K tokens Token VF: {value} AFP VF: {value} API Cost This Sprint: $___ $/FP This Sprint: $___ $/FP Calibrated: $___ Deferred: {list deferred scenarios and reason} Revised Forecast (remaining work): Internal: P50 = {K tokens / days} P80 = {K tokens / days} Client: P80 AFP = ___ → $___ Token Budget Status: Consumed to date: {K} tokens Remaining P80: {K} tokens Total P80: {K} tokens ({% of original P80}) Next sprint: {N} scenarios ({SP} SP / {FP} FP) ``` Present to user/stakeholder. Save to `docs/plans/`. ## Rules to Follow ### I. Actuals Are Sacred Never retroactively adjust planned estimates to match actuals. Both must be preserved as separate columns. ### II. BPE-08 Before Calibration Data Any scope change must be processed through BPE-08 first. Do not blend scope-change overruns into K-token calibration — they will corrupt future baselines. ### III. $/FP Updates Require ≥ 3 Sprints to CALIBRATE 1–2 sprints → BORROWED rate. 3+ sprints → CALIBRATED. Do not price future work off a single sprint anomaly. ### IV. FP Weights Are Fixed — SP Can Move FP weights represent the client-committed value per scenario. Do not retroactively change FP weights after quoting. SP values and K-token baselines are internal calibration variables and can be updated freely. ### V. Investigate AFP VF < 0.8 A sprint where significantly less FP was delivered than quoted is a scope or quality signal. Before re-quoting remaining work, understand why: deferred features? Failed DoD? Unexpected complexity? ### VI. The 20-Data-Point Threshold Monte Carlo achieves MMRE ~20% only after ~20 data points (ACM SAC 2021). Before that, keep PERT ranges wide. ## Success Criteria - Sprint actuals collected (tokens, FP delivered, API cost) - Token VF and AFP VF computed - K-token baselines updated in Setup tab - $/FP calibrated from actuals; status updated (SEED → CALIBRATED after 3 sprints) - Reference Table §11 appended - ECF/TCF re-rated if warranted - Remaining scenario token estimates updated - Monte Carlo re-run, new P50/P80/P95 for tokens and AFP/$ - MC_SNAPSHOT saved, sprint report produced and reviewed - Client Quote tab $/FP updated ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - Estimation Reference Table (Document, Required) — produced by Calibrate Reference Stories (#67). - Estimation Template (Excel) (Document, Required) — produced by Size Scenarios (Level 1 SWAG) (#68). - Execution Manifest (Document, Required) — produced by Contract (#142). - GitHub Release (Other, Required) — produced by Close Iteration (#118). - Lessons Learned Document (Document, Optional) — produced by Close Iteration (#118).
Design & Deploy Cloud Infra
#1	Review SAO & Define Infra Requirements	Read the 'DCI-1 Review SAO & Define Infra Requirements' activity from playbook 'Junior Edda' (workflow 'Design & Deploy Cloud Infra'). Follow its guidance when assisting me. # Review SAO & Define Infra Requirements ## Objective Read `docs/architecture/SAO.md`, identify the AWS services needed for the application, and produce a concise infrastructure requirements document that drives all subsequent CDK stack decisions. --- ## Process ### 1. Read SAO.md Extract from SAO.md: - Technology Stack Table — runtime versions, databases, caches, queues - § Deployment Strategy (DTA-14) — blue/green, canary, rolling - § Infrastructure (DTA-15) — cloud provider, region, compute platform - § Observability (DTA-13) — logging, metrics, tracing services ### 2. Map Application Needs → AWS Services \| Application Need \| EKS Path \| EB Path \| CDK Stack \| \|-----------------\|----------\|---------\|----------\| \| Container orchestration \| EKS \| Elastic Beanstalk \| EKS Stack / EB Stack \| \| Container registry \| ECR \| ECR \| EKS Stack / EB Stack \| \| Networking (VPC, subnets) \| VPC \| VPC \| VPC Stack \| \| DNS for blue/green \| Route53 \| Route53 (via CNAME swap) \| DNS Stack / EB handles internally \| \| NAT for private subnets \| NAT Gateway \| NAT Gateway \| VPC Stack \| \| TLS termination \| ALB + ACM \| EB managed ALB \| EKS Stack (ingress) / EB handles \| \| Secrets \| AWS Secrets Manager or K8s Secrets \| Secrets Manager or EB env properties \| EKS Stack / EB Stack \| \| Logging \| CloudWatch Logs \| CloudWatch Logs \| EKS Stack (add-ons) / EB handles \| ### 3. Choose Deployment Style Read the infrastructure skills available in this playbook. Pick one based on SAO.md § Deployment Strategy and § Infrastructure decisions: \| Style \| When to choose \| Skill \| \|---\|---\|---\| \| Kubernetes / EKS \| Multi-service, needs orchestration, team familiar with K8s \| K8s in EKS Deployment Patterns (#23) \| \| Elastic Beanstalk \| Single-service Django/web app, small team, want managed infra \| AWS EB Blue/Green Deployment \| Record the choice in `INFRA_REQUIREMENTS.md` under a new "Deployment Style" heading: ```markdown ## Deployment Style Chosen: [EKS / Elastic Beanstalk] Rationale: [Why this style fits the project — team size, service count, K8s familiarity, etc.] Skill Reference: [Skill name and ID] ``` All subsequent DCI and DCD activities must be executed using the patterns from the chosen skill. ### 4. Document Infra Requirements Create `docs/architecture/INFRA_REQUIREMENTS.md`. Tailor the content to your chosen deployment style: #### EKS Path ```markdown # Infrastructure Requirements ## AWS Region {region from SAO.md, e.g., us-east-1} ## Deployment Style Chosen: Kubernetes / EKS Rationale: Multi-service architecture with microservices orchestration needs Skill Reference: K8s in EKS Deployment Patterns (#23) ## Services Required \| Service \| Purpose \| Configuration \| \|---------\|---------\|---------------\| \| VPC \| Network isolation \| 2 public + 2 private subnets, NAT GW \| \| EKS \| Container orchestration \| Managed node group, 2-3 nodes \| \| ECR \| Container registry \| 1 repo per service \| \| Route53 \| DNS + blue/green switching \| Hosted zone, prod/idle weighted records \| ## Blue/Green Strategy - Two namespaces: `blue`, `green` - Route53 weighted records: `prod.{domain}` → active, `idle.{domain}` → standby - Switch = swap DNS weights (0/100 ↔ 100/0) ## Cost Estimate {Rough monthly cost for EKS + NAT + Route53} ## Security Requirements - Private subnets for EKS nodes - Security groups: EKS ↔ database, ALB ↔ EKS - IAM roles: EKS node role, CDK deploy role ``` #### EB Path ```markdown # Infrastructure Requirements ## AWS Region {region from SAO.md, e.g., us-east-1} ## Deployment Style Chosen: Elastic Beanstalk Rationale: Single Django application, small team, prefer managed infrastructure Skill Reference: AWS EB Blue/Green Deployment ## Services Required \| Service \| Purpose \| Configuration \| \|---------\|---------\|---------------\| \| VPC \| Network isolation \| 2 public + 2 private subnets, NAT GW \| \| Elastic Beanstalk \| Managed Docker platform \| 2 environments: {project}-prod, {project}-idle \| \| ECR \| Container registry \| 1 repo for web image \| \| S3 \| Deployment bundles \| elasticbeanstalk-{region}-{account} \| ## Blue/Green Strategy - Two EB environments: `{project}-prod` (physical A), `{project}-idle` (physical B) - CNAME swap: `swap-environment-cnames` flips prod ↔ idle roles - Prod is whichever env currently holds the `{project}-prod` CNAME ## Environment Variables - `EB_APP`: {project} - `EB_ENV_A`: {project}-prod - `EB_ENV_B`: {project}-idle - `EB_BUCKET`: elasticbeanstalk-{region}-{account} ## Cost Estimate {Rough monthly cost for 2 EB environments + NAT + S3} ## Security Requirements - Private subnets for EB instances - Security groups: EB ALB ↔ instances - IAM roles: EB service role, instance profile ``` ### 5. Validate with SAO.md Cross-check: every service in INFRA_REQUIREMENTS.md must trace back to a decision in SAO.md. If SAO.md doesn't cover infra decisions, flag it and update DTA first. --- ## Deliverables - ✅ SAO.md reviewed — infra-relevant sections extracted - ✅ Deployment style chosen — EKS or EB, documented with rationale - ✅ AWS service mapping — application needs → AWS services (both paths shown) - ✅ `docs/architecture/INFRA_REQUIREMENTS.md` created (tailored to chosen style) - ✅ Blue/green strategy documented (style-specific) - ✅ Cost estimate included ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - System Architecture Overview Template (Template, Required) — produced by Write SAO.md (#59).
#2	Scaffold Infra Repo & CDK Project	Read the 'DCI-2 Scaffold Infra Repo & CDK Project' activity from playbook 'Junior Edda' (workflow 'Design & Deploy Cloud Infra'). Follow its guidance when assisting me. # Scaffold Infra Repo & CDK Project ## Objective Create an AWS CDK Python project with Makefile for infra operations and a GitHub Actions workflow placeholder. Layout depends on deployment style from DCI-01. --- ## Process ### Path Selection Refer to `docs/architecture/INFRA_REQUIREMENTS.md` § Deployment Style. \| Style \| Repo layout \| \|-------\|-------------\| \| EKS \| Separate `{project}-infra` repository (recommended) \| \| Elastic Beanstalk \| `{project}-infra/` or `infra/` inside the application monorepo \| > Monorepo note (EB): Small teams often keep `infra/` in the app repo. CDK deploy and app CI/CD share secrets via `infra/.env`. Separate repo still valid for larger orgs. --- ## EKS Path ### 1. Create Infra Repository ```bash mkdir {project}-infra && cd {project}-infra && git init ``` ### 2. Initialize CDK Project ```bash python3 -m venv .venv && source .venv/bin/activate pip install aws-cdk-lib constructs mkdir -p stacks tests ``` Create `app.py` wiring `VpcStack`, `EksStack`, `DnsStack`. ### 3. Directory Structure ``` {project}-infra/ ├── app.py ├── cdk.json ├── requirements.txt ├── Makefile ├── .github/workflows/infra.yml ├── stacks/ │ ├── vpc_stack.py │ ├── eks_stack.py │ └── dns_stack.py ├── scripts/traffic_switch.py └── tests/test_stacks.py ``` --- ## Elastic Beanstalk Path ### 1. Create `infra/` Directory In app monorepo (or separate repo): ```bash mkdir -p infra/stacks infra/scripts infra/tests infra/lambda ``` ### 2. Initialize CDK Project Same venv/CDK setup as EKS path. Create `app.py` wiring stacks for your project, e.g.: - `MimirNetwork` — VPC lookup, EB security group, RDS ingress - `MimirApp` — EB app, `{project}-prod` / `{project}-idle`, ECR ref, CI IAM, alarms - `MimirBackups` — S3 pre-migrate bucket, SSM on EB instance role - `MimirSes` — SES configuration set (if transactional email) - `MimirDns` — Route53 CNAME → `{project}-prod.eba-…` (see DCI-05 EB path) ### 3. Directory Structure ``` infra/ ├── app.py ├── cdk.json ├── requirements.txt ├── .env.example ← secrets template (gitignored .env) ├── eb_live_platform_settings.json ← exported from live EB (no secrets) ├── stacks/ │ ├── network_stack.py │ ├── app_stack.py ← EB + ECR + CI IAM │ ├── backups_stack.py │ ├── ses_stack.py │ └── dns_stack.py ├── scripts/ │ ├── export_eb_live_settings.py │ └── diff_eb_live_vs_cdk.py ├── lambda/route53_cname/ ← idempotent CNAME UPSERT └── tests/test_stacks.py ``` ### 4. Two Sources of Truth (EB) \| What \| Where \| \|------\|--------\| \| Platform settings (VPC, ALB, instance type, non-secret env vars) \| `eb_live_platform_settings.json` — refresh after console changes \| \| Secrets (`DATABASE_URL`, `DJANGO_SECRET_KEY`, etc.) \| `infra/.env` at `cdk deploy` — never committed \| See AWS CDK with Python skill § EB Platform Settings Export. --- ## Infra Makefile (Both Paths) ```makefile .PHONY: help synth deploy destroy status test provision help: ## Show help @awk 'BEGIN {FS = ":.##"} /^[a-zA-Z_-]+:.?##/ { printf " %-20s %s\n", $$1, $$2 }' $(MAKEFILE_LIST) synth: ## Synthesize CDK stacks cdk synth deploy: ## Deploy all stacks cdk deploy --all --require-approval never test: ## Run CDK tests python -m pytest tests/ -v provision: ## Install CDK deps pip install -r requirements.txt ``` EB monorepo: add `##@ Deploy` targets to the app Makefile (`swap`, `eb-status`, `backup`) — see EB skill. --- ## Deliverables - ✅ CDK project initialized with stack placeholders for chosen style - ✅ Infra Makefile with synth/deploy/test targets - ✅ EB: `.env.example` + export/diff scripts scaffolded - ✅ Committed
#3	Build VPC & Networking Stack	Read the 'DCI-3 Build VPC & Networking Stack' activity from playbook 'Junior Edda' (workflow 'Design & Deploy Cloud Infra'). Follow its guidance when assisting me. # Build VPC & Networking Stack ## Objective Implement the VPC CDK stack with public/private subnets, NAT Gateway, and security groups. This is the foundational networking layer that EKS and all other services depend on. --- ## Process ### 1. Implement `stacks/vpc_stack.py` Use the `aws_cdk_python` skill for reference patterns. Key constructs: - VPC with 2 AZs, 2 public + 2 private subnets - NAT Gateway (1 per AZ for HA, or 1 shared for cost savings) - Security Groups: EKS control plane, EKS nodes, database (if applicable) ```python from aws_cdk import Stack, aws_ec2 as ec2 from constructs import Construct class VpcStack(Stack): def __init__(self, scope: Construct, id: str, kwargs): super().__init__(scope, id, kwargs) self.vpc = ec2.Vpc( self, "Vpc", max_azs=2, nat_gateways=1, 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 nodes self.eks_sg = ec2.SecurityGroup( self, "EksNodeSg", vpc=self.vpc, description="Security group for EKS worker nodes", allow_all_outbound=True, ) ``` ### 2. Write CDK Tests ```python # tests/test_vpc_stack.py import aws_cdk as cdk from aws_cdk.assertions import Template from stacks.vpc_stack import VpcStack def test_vpc_created(): app = cdk.App() stack = VpcStack(app, "TestVpc") template = Template.from_stack(stack) template.resource_count_is("AWS::EC2::VPC", 1) def test_subnets_created(): app = cdk.App() stack = VpcStack(app, "TestVpc") template = Template.from_stack(stack) template.resource_count_is("AWS::EC2::Subnet", 4) # 2 public + 2 private ``` ### 3. Synthesize & Verify ```bash make synth # Should produce CloudFormation template without errors make test # CDK tests should pass ``` ### 4. Deploy VPC Stack Only ```bash npx cdk deploy VpcStack ``` Verify in AWS Console: - VPC created with correct CIDR - 4 subnets (2 public, 2 private) - NAT Gateway running - Route tables configured ### 5. Commit ```bash git add stacks/vpc_stack.py tests/test_vpc_stack.py git commit -m "infra: implement VPC stack with 2 AZ, NAT Gateway, security groups" ``` --- ## Deliverables - ✅ `stacks/vpc_stack.py` implemented with VPC, subnets, NAT, security groups - ✅ CDK tests for VPC stack passing - ✅ `make synth` succeeds - ✅ VPC deployed and verified in AWS Console
#4	Build Compute & Container Registry Stack	Read the 'DCI-4 Build Compute & Container Registry Stack' activity from playbook 'Junior Edda' (workflow 'Design & Deploy Cloud Infra'). Follow its guidance when assisting me. # Build Compute & Container Registry Stack ## Objective Provision the compute environment and container registry matching your chosen deployment style (from Activity #74). This activity forks into two implementation paths—EKS or Elastic Beanstalk—both delivering the same outcome: a running compute platform and accessible ECR repository. --- ## Process ### Path Selection Refer to `docs/architecture/INFRA_REQUIREMENTS.md` § Deployment Style. Follow the path for your chosen style. --- ## EKS Path Skill: K8s in EKS Deployment Patterns (#23) ### 1. Implement `stacks/eks_stack.py` Key constructs: - EKS Cluster with managed node group (2-3 `t3.medium` nodes) - ECR Repository for application container images - OIDC Provider for IAM Roles for Service Accounts (IRSA) - kubectl layer for CDK to interact with cluster - Blue/green namespaces created on cluster ```python from aws_cdk import Stack, RemovalPolicy, aws_eks as eks, aws_ec2 as ec2, aws_ecr as ecr, aws_iam as iam from constructs import Construct class EksStack(Stack): def __init__(self, scope: Construct, id: str, vpc: ec2.Vpc, kwargs): 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}", 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}, }, ) ``` ### 2. Configure kubectl Access ```bash aws eks update-kubeconfig --name {cluster-name} --region {region} kubectl get nodes # Should show 2 worker nodes kubectl get ns # Should show blue and green namespaces ``` ### 3. Test ECR Push ```bash aws ecr get-login-password --region {region} \| docker login --username AWS --password-stdin {account}.dkr.ecr.{region}.amazonaws.com docker pull nginx:alpine docker tag nginx:alpine {account}.dkr.ecr.{region}.amazonaws.com/{project}:test docker push {account}.dkr.ecr.{region}.amazonaws.com/{project}:test ``` --- ## Elastic Beanstalk Path Skill: AWS EB Blue/Green Deployment ### 1. Implement `stacks/eb_stack.py` Key constructs: - EB Application resource - Two EB Environments: `{project}-prod` (physical A), `{project}-idle` (physical B) - ECR Repository for Docker images - S3 Bucket for deployment bundles (use existing `elasticbeanstalk-{region}-{account}` bucket) ```python from aws_cdk import Stack, RemovalPolicy, aws_elasticbeanstalk as eb, aws_ec2 as ec2, aws_ecr as ecr, aws_iam as iam from constructs import Construct class EbStack(Stack): def __init__(self, scope: Construct, id: str, vpc: ec2.Vpc, kwargs): super().__init__(scope, id, kwargs) # EB Application self.app = eb.CfnApplication( self, "App", application_name="{project}", ) # ECR Repository self.ecr_repo = ecr.Repository( self, "AppRepo", repository_name="{project}", removal_policy=RemovalPolicy.RETAIN, lifecycle_rules=[ ecr.LifecycleRule(max_image_count=20, description="Keep last 20 images") ], ) # Service Role for EB service_role = iam.Role( self, "EBServiceRole", assumed_by=iam.ServicePrincipal("elasticbeanstalk.amazonaws.com"), managed_policies=[ iam.ManagedPolicy.from_aws_managed_policy_name("AWSElasticBeanstalkEnhancedHealth"), iam.ManagedPolicy.from_aws_managed_policy_name("AWSElasticBeanstalkManagedUpdatesCustomerRolePolicy"), ], ) # Instance Profile instance_role = iam.Role( self, "EBInstanceRole", assumed_by=iam.ServicePrincipal("ec2.amazonaws.com"), managed_policies=[ iam.ManagedPolicy.from_aws_managed_policy_name("AWSElasticBeanstalkWebTier"), iam.ManagedPolicy.from_aws_managed_policy_name("AmazonEC2ContainerRegistryReadOnly"), ], ) instance_profile = iam.CfnInstanceProfile( self, "EBInstanceProfile", roles=[instance_role.role_name], ) # Environment A ({project}-prod initially) self.env_a = eb.CfnEnvironment( self, "EnvA", application_name=self.app.application_name, environment_name="{project}-prod", solution_stack_name="64bit Amazon Linux 2023 v4.3.0 running Docker", option_settings=[ eb.CfnEnvironment.OptionSettingProperty( namespace="aws:autoscaling:launchconfiguration", option_name="IamInstanceProfile", value=instance_profile.ref, ), eb.CfnEnvironment.OptionSettingProperty( namespace="aws:elasticbeanstalk:environment", option_name="ServiceRole", value=service_role.role_arn, ), ], ) self.env_a.add_dependency(self.app) # Environment B ({project}-idle initially) self.env_b = eb.CfnEnvironment( self, "EnvB", application_name=self.app.application_name, environment_name="{project}-idle", solution_stack_name="64bit Amazon Linux 2023 v4.3.0 running Docker", option_settings=[ eb.CfnEnvironment.OptionSettingProperty( namespace="aws:autoscaling:launchconfiguration", option_name="IamInstanceProfile", value=instance_profile.ref, ), eb.CfnEnvironment.OptionSettingProperty( namespace="aws:elasticbeanstalk:environment", option_name="ServiceRole", value=service_role.role_arn, ), ], ) self.env_b.add_dependency(self.app) ``` ### 2. Document EB Variables Add to `INFRA_REQUIREMENTS.md`: ```markdown ## EB Environment Variables (for CI/CD) - `EB_APP`: {project} - `EB_ENV_A`: {project}-prod - `EB_ENV_B`: {project}-idle - `EB_BUCKET`: elasticbeanstalk-{region}-{account} ``` ### 3. Verify EB Environments ```bash aws elasticbeanstalk describe-environments \ --application-name {project} \ --query 'Environments[].{Name:EnvironmentName,Status:Status,Health:Health,CNAME:CNAME}' \ --output table ``` Both environments should show `Status=Ready`. ### 4. Test ECR Push ```bash aws ecr get-login-password --region {region} \| docker login --username AWS --password-stdin {account}.dkr.ecr.{region}.amazonaws.com docker pull nginx:alpine docker tag nginx:alpine {account}.dkr.ecr.{region}.amazonaws.com/{project}:test docker push {account}.dkr.ecr.{region}.amazonaws.com/{project}:test ``` --- ## Commit (Both Paths) ```bash git add stacks/ git commit -m "infra: implement compute and container registry stack ({EKS\|EB})" ``` --- ## Deliverables (Style-Agnostic) - ✅ Compute environment running (EKS cluster with nodes OR two EB environments) - ✅ ECR repository accessible (push/pull verified) - ✅ Blue/green substrate in place (K8s namespaces OR EB environment pair) - ✅ Chosen style recorded in `INFRA_REQUIREMENTS.md` - ✅ CDK stack committed ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - Infra Repo Scaffold (Template, Required) — produced by Scaffold Infra Repo & CDK Project (#75). - VPC Stack (Code, Required) — produced by Build VPC & Networking Stack (#76). - INFRA_REQUIREMENTS.md (Document, Required) — produced by Review SAO & Define Infra Requirements (#74).
#5	Build Route53 & DNS Stack	Read the 'DCI-5 Build Route53 & DNS Stack' activity from playbook 'Junior Edda' (workflow 'Design & Deploy Cloud Infra'). Follow its guidance when assisting me. # Build Route53 & DNS Stack ## Objective Implement DNS for blue/green traffic routing. Implementation differs by deployment style — do not mix patterns. --- ## Path Selection Refer to `INFRA_REQUIREMENTS.md` § Deployment Style. \| Style \| DNS model \| Switch mechanism \| \|-------\|-----------\|------------------\| \| EKS \| Weighted records: `prod.{domain}`, `idle.{domain}` \| `traffic_switch.py` swaps weights \| \| Elastic Beanstalk \| Single CNAME: `{domain}` → `{project}-prod.eba-…` \| EB `swap-environment-cnames` (no Route53 edit on promote) \| --- ## EKS Path Skill: AWS CDK with Python § Route53 Hosted Zone ### 1. Implement `stacks/dns_stack.py` Create hosted zone. Weighted prod/idle records managed by `scripts/traffic_switch.py` (not CDK) to avoid drift. ### 2. Create `scripts/traffic_switch.py` Actions: `switch`, `rollback`, `status` — swap Route53 weighted record targets. ### 3. Infra Makefile targets ```makefile traffic-switch: ## Swap prod/idle DNS weights python scripts/traffic_switch.py --action switch traffic-rollback: ## Restore previous weights python scripts/traffic_switch.py --action rollback ``` ### 4. Verify ```bash dig prod.{domain} dig idle.{domain} make traffic-switch && dig prod.{domain} # target changed ``` --- ## Elastic Beanstalk Path Skill: AWS EB Blue/Green Deployment § Pattern 7: Route53 for EB ### 1. DNS Mental Model ``` Public: https://app.example.com ↓ Route53 CNAME (TTL 60s) app-prod.eba-xxxxx.elasticbeanstalk.com ← fixed label name ↓ EB swap-environment-cnames whichever physical env currently owns that label ``` Critical: Route53 must point at the EB environment CNAME label (`{project}-prod.eba-…`), not the ALB ARN directly. ALB-alias breaks CNAME swap — live traffic won't follow promotion. ### 2. Implement `stacks/dns_stack.py` Use an idempotent Lambda custom resource to UPSERT the CNAME (avoids `ConflictingResourceExists` on re-deploy): ```python # Route53 CNAME: app.example.com → {project}-prod.eba-xxxxx.elasticbeanstalk.com # Lambda handler: ListResourceRecordSets + ChangeResourceRecordSets (UPSERT) ``` HTTPS terminates at the EB-managed ALB (ACM cert on :443 listener). No CloudFront required for basic setup. ### 3. No traffic_switch.py for EB Promotion is only `aws elasticbeanstalk swap-environment-cnames` (see EB skill Pattern 2). Route53 record stays fixed; EB rotates which env owns the `{project}-prod` label. ### 4. Verify ```bash dig +short app.example.com # Must resolve to whichever env currently holds app-prod.eba-… label make swap # in app repo sleep 90 # Route53 TTL + resolver cache dig +short app.example.com # same CNAME label, different backend env ``` --- ## Deliverables - ✅ EKS: hosted zone + `traffic_switch.py` + make targets - ✅ EB: CNAME to prod EB label via idempotent Lambda UPSERT - ✅ EB: documented why ALB-alias Route53 breaks swap - ✅ CDK tests passing - ✅ DNS resolving correctly for chosen style
#6	Create Infra GH Workflow	Read the 'DCI-6 Create Infra GH Workflow' activity from playbook 'Junior Edda' (workflow 'Design & Deploy Cloud Infra'). Follow its guidance when assisting me. # Create Infra GitHub Actions Workflow ## Objective Create a GitHub Actions workflow that automates CDK infrastructure deployment. Traffic switching is not in this workflow for EB — it lives in the app repo (`make swap` / `promote.yml`). --- ## Path Selection \| Style \| Infra workflow scope \| Traffic switch location \| \|-------\|---------------------\|------------------------\| \| EKS \| `cdk deploy` + optional `traffic-switch` job \| Infra repo `make traffic-switch` \| \| Elastic Beanstalk \| `cdk deploy` only \| App repo `promote.yml` or `make swap` \| --- ## Shared Pattern: Thin Wrapper Around Make ```yaml name: Infrastructure on: push: branches: [main] paths: - 'infra/' # monorepo layout # OR 'stacks/' # separate infra repo - 'cdk.json' workflow_dispatch: inputs: action: type: choice options: [deploy, status] permissions: id-token: write contents: read jobs: infra: runs-on: ubuntu-latest environment: infrastructure steps: - uses: actions/checkout@v4 - uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_ROLE_ARN }} aws-region: ${{ vars.AWS_REGION }} - uses: actions/setup-python@v5 with: python-version: '3.12' - run: make provision - run: make deploy # or: cd infra && cdk deploy --all ``` > Auth: Prefer OIDC (`role-to-assume`). IAM access keys acceptable for single-team projects — see GitHub Actions Patterns skill § Release-Triggered Deploy. --- ## EKS Path Additions Add manual `traffic-switch` and `traffic-rollback` jobs with `environment: production` approval gate: ```yaml traffic-switch: if: github.event.inputs.action == 'traffic-switch' environment: production steps: - run: make traffic-switch ``` --- ## Elastic Beanstalk Path Do not add traffic-switch to infra workflow. Document in README: ```markdown ## Infra vs App deploy - Infra (this workflow): `cdk deploy --all` — VPC, EB envs, DNS CNAME, backups bucket - App (build-and-deploy.yml): test → ECR push → deploy-idle.sh → smoke - Promote (promote.yml or `make swap`): CNAME swap after human review ``` Refresh platform snapshot after console EB changes: ```bash python infra/scripts/export_eb_live_settings.py python infra/scripts/diff_eb_live_vs_cdk.py # expect 0 diffs before deploy ``` --- ## GitHub Environments \| Environment \| Reviewers \| Used for \| \|-------------\|-----------\|----------\| \| `infrastructure` \| 0–1 \| CDK deploy \| \| `production` \| 1–2 \| EKS traffic-switch or app promote.yml \| --- ## Deliverables - ✅ `.github/workflows/infra.yml` (or in `infra/.github/…` for separate repo) - ✅ CDK deploy on infra path changes - ✅ EB: no traffic-switch in infra workflow - ✅ EKS: optional traffic-switch with production approval - ✅ Workflow tested
#7	Deploy & Verify Cloud Environment	Read the 'DCI-7 Deploy & Verify Cloud Environment' activity from playbook 'Junior Edda' (workflow 'Design & Deploy Cloud Infra'). Follow its guidance when assisting me. # Deploy & Verify Cloud Environment ## Objective Run full infrastructure deployment, verify AWS resources, and confirm blue/green switching end-to-end. Acceptance gate for DCI workflow. Follow the path matching your deployment style. --- ## Path Selection Refer to `INFRA_REQUIREMENTS.md` § Deployment Style. --- ## EKS Path ### 1. Full Deployment ```bash cd {project}-infra && make deploy ``` Expected: ~20–25 min (EKS cluster dominates). ### 2. Verify VPC, EKS, ECR, DNS ```bash kubectl get nodes # 2 Ready kubectl get ns # blue, green aws ecr describe-repositories dig prod.{domain} && dig idle.{domain} make traffic-switch && make traffic-rollback ``` ### 3. Document in `docs/architecture/INFRA_VERIFICATION.md` Use EKS checklist (VPC, subnets, NAT, EKS nodes, namespaces, ECR, Route53 weights, GH Actions deploy). --- ## Elastic Beanstalk Path ### 1. Full Deployment ```bash cd infra && cdk deploy --all --require-approval never ``` Expected: ~10–15 min (no EKS). ### 2. Verify Platform Snapshot ```bash python scripts/export_eb_live_settings.py python scripts/diff_eb_live_vs_cdk.py # Expect 0 platform diffs (secrets excluded) ``` ### 3. Verify EB Environments ```bash aws elasticbeanstalk describe-environments \ --application-name {project} \ --query 'Environments[].{Name:EnvironmentName,Status:Status,Health:Health,CNAME:CNAME,Version:VersionLabel}' \ --output table ``` Both `{project}-prod` and `{project}-idle` should be `Ready`. ### 4. Verify ECR, DNS, Backups ```bash # ECR push test aws ecr get-login-password \| docker login ... docker push {account}.dkr.ecr.{region}.amazonaws.com/{project}:verify-test # DNS: public domain → prod EB label dig +short app.example.com # S3 backup bucket exists aws s3 ls s3://{project}-db-backups-{account}/ # SSM: EB instances managed aws ssm describe-instance-information --filters Key=tag:elasticbeanstalk:environment-name,Values={project}-idle ``` ### 5. End-to-End Blue/Green (with app pipeline) Full acceptance requires app deploy — coordinate with DCD: ```bash gh release create v0.0.1-test # CI: deploy-idle.sh → idle smoke curl http://{idle-cname}/health/ # revision matches make swap # CNAME swap + prod smoke curl https://app.example.com/health/ ``` ### 6. Document in `docs/architecture/INFRA_VERIFICATION.md` \| Check \| Status \| Details \| \|-------\|--------\|---------\| \| VPC / SG \| ✅ \| … \| \| EB app + 2 envs \| ✅ \| Ready, Green/Yellow \| \| Platform snapshot diff \| ✅ \| 0 diffs \| \| ECR push/pull \| ✅ \| … \| \| Route53 CNAME → prod label \| ✅ \| not ALB-alias \| \| S3 backup bucket \| ✅ \| lifecycle 90d \| \| SSM on EB instances \| ✅ \| SendCommand works \| \| Idle deploy + smoke \| ✅ \| revision match \| \| CNAME swap + prod smoke \| ✅ \| HTTPS revision match \| --- ## Deliverables - ✅ All CDK stacks deployed for chosen style - ✅ Blue/green mechanism verified (Route53 weights or EB CNAME swap) - ✅ `docs/architecture/INFRA_VERIFICATION.md` documented - ✅ GH Actions infra deploy passing
Design & Deploy CICD
#1	Review SAO & Define CICD Requirements	Read the 'DCD-1 Review SAO & Define CICD Requirements' activity from playbook 'Junior Edda' (workflow 'Design & Deploy CICD'). Follow its guidance when assisting me. # Review SAO & Define CICD Requirements ## Objective Read `docs/architecture/SAO.md` and DCI output. Define pipeline stages, map to `make` targets, produce `CICD_REQUIREMENTS.md`. Pipeline shape depends on deployment style. --- ## Process ### 1. Read SAO.md Extract § Deployment Strategy, § Test Strategy, § CI/CD Pipeline. ### 2. Review DCI Output \| Style \| Confirm available \| \|-------\|-------------------\| \| EKS \| Cluster name, ECR URI, Route53 domain, `make traffic-switch` \| \| Elastic Beanstalk \| EB app/env names, ECR URI, `deploy-idle.sh`, `make swap`, S3 backup bucket \| ### 3. Choose Trigger Model \| Model \| When \| Trigger \| \|-------\|------\|---------\| \| Continuous \| Fast iteration, trunk-based \| Push to `main` → test + build \| \| Release-gated (Huginn) \| Production control, semver releases \| `gh release create vX.Y.Z` → test + build + deploy-idle \| Document choice in `CICD_REQUIREMENTS.md`. ### 4. Map Pipeline Stages → Make Targets #### EKS Path \| Stage \| Target \| Gate \| \|-------\|--------\|------\| \| Test \| `make test` \| All pass \| \| Build \| `make containers` \| ECR push \| \| Deploy idle \| `make deploy ENV=idle` \| Pods healthy \| \| Smoke \| `make smoke-test ENV=idle` \| Pass \| \| Switch \| `make switch` → infra `traffic-switch` \| Manual approval \| \| Verify prod \| `make smoke-test ENV=prod` \| Pass \| #### Elastic Beanstalk Path \| Stage \| Target \| Gate \| \|-------\|--------\|------\| \| Test \| `make test` \| All pass \| \| Build \| CI: ECR push (+ optional Docker Hub for client tools) \| Images pushed \| \| Backup \| `deploy-idle.sh` step 2 (SSM) \| S3 keys exist \| \| Deploy idle \| `deploy-idle.sh` \| EB Ready, Health ≠ Red \| \| Smoke \| `/health/` revision on idle CNAME \| Match `GIT_REVISION` \| \| Promote \| `make swap` or `promote.yml` \| Manual approval \| \| Verify prod \| `/health/` on HTTPS custom domain \| Revision match \| ### 5. Document CICD Requirements Create `docs/architecture/CICD_REQUIREMENTS.md` — see artifact template CICD Requirements (EB Reference). --- ## Deliverables - ✅ SAO.md reviewed - ✅ DCI output confirmed for chosen style - ✅ Trigger model documented (continuous vs release-gated) - ✅ Pipeline stages mapped to make targets - ✅ `CICD_REQUIREMENTS.md` created
#2	Create Helm Chart & Values	Read the 'DCD-2 Create Helm Chart & Values' activity from playbook 'Junior Edda' (workflow 'Design & Deploy CICD'). Follow its guidance when assisting me. # Create Deployment Manifest ## Objective Create a versioned, per-environment deployment artifact that CI/CD uses to deploy the application. The artifact format depends on your deployment style (from Activity #74): Helm chart for Kubernetes/EKS, or Docker Compose template for Elastic Beanstalk. --- ## Process ### Path Selection Refer to `docs/architecture/INFRA_REQUIREMENTS.md` § Deployment Style. Follow the path for your chosen style. --- ## Kubernetes / EKS Path Skill: K8s in EKS Deployment Patterns (#23) ### 1. Create Helm Chart Structure ```bash mkdir -p deploy/helm/{project}/templates ``` ### 2. Create Chart.yaml ```yaml # deploy/helm/{project}/Chart.yaml apiVersion: v2 name: {project} description: Helm chart for {project} application type: application version: 0.1.0 appVersion: "0.1.0" ``` ### 3. Create Templates deployment.yaml: ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: {{ .Release.Name }} namespace: {{ .Values.namespace \| default .Release.Namespace }} spec: replicas: {{ .Values.replicaCount }} selector: matchLabels: app: {{ .Release.Name }} template: metadata: labels: app: {{ .Release.Name }} spec: containers: - name: app image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}" imagePullPolicy: {{ .Values.image.pullPolicy }} ports: - containerPort: {{ .Values.service.targetPort }} envFrom: - configMapRef: name: {{ .Release.Name }}-config livenessProbe: httpGet: path: /health port: {{ .Values.service.targetPort }} initialDelaySeconds: 15 periodSeconds: 10 readinessProbe: httpGet: path: /health port: {{ .Values.service.targetPort }} initialDelaySeconds: 5 periodSeconds: 5 resources: {{- toYaml .Values.resources \| nindent 12 }} ``` service.yaml: ```yaml apiVersion: v1 kind: Service metadata: name: {{ .Release.Name }} namespace: {{ .Values.namespace \| default .Release.Namespace }} spec: type: {{ .Values.service.type }} selector: app: {{ .Release.Name }} ports: - port: {{ .Values.service.port }} targetPort: {{ .Values.service.targetPort }} ``` configmap.yaml: ```yaml apiVersion: v1 kind: ConfigMap metadata: name: {{ .Release.Name }}-config namespace: {{ .Values.namespace \| default .Release.Namespace }} data: {{- range $key, $value := .Values.config }} {{ $key }}: {{ $value \| quote }} {{- end }} ``` ### 4. Create Values Files 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" ``` values-local.yaml, values-blue.yaml, values-green.yaml (per-environment overrides). ### 5. Verify Helm Template ```bash helm lint deploy/helm/{project} helm template {project} deploy/helm/{project} -f deploy/helm/{project}/values-local.yaml ``` --- ## Elastic Beanstalk Path Skill: AWS EB Blue/Green Deployment ### 1. Create Docker Compose Template EB uses a `docker-compose.yml` file to define the container. Create a template with environment variable substitution: ```yaml # deploy/docker-compose.tmpl.yml version: "3.8" services: web: image: ${IMAGE_WEB} ports: - "80:8000" environment: - MIMIR_ENV=production - DJANGO_SETTINGS_MODULE=mimir.settings restart: always ``` ### 2. Create Render Script CI/CD will substitute `IMAGE_WEB` at deploy time: ```bash # In .github/workflows/build-and-deploy.yml env: IMAGE_WEB: ${{ steps.ecr-login.outputs.registry }}/mimir:${{ steps.version.outputs.suffix }} run: \| envsubst '$IMAGE_WEB' < deploy/docker-compose.tmpl.yml > docker-compose.yml cat docker-compose.yml ``` ### 3. Create Deployment Bundle EB requires a `.zip` bundle containing `docker-compose.yml`: ```bash # In CI/CD zip -j deploy-bundle.zip docker-compose.yml ``` This bundle is uploaded to S3 and referenced when creating an EB application version. See AWS EB Blue/Green Deployment skill Pattern 1 for full `deploy-idle.sh` script. ### 4. Document Deployment Flow Add to `README.md` or `docs/deployment.md`: ```markdown ## EB Deployment Flow 1. CI builds Docker image, pushes to ECR 2. Render `docker-compose.yml` from template with `IMAGE_WEB={ecr-uri}:{tag}` 3. Zip `docker-compose.yml` → `deploy-bundle.zip` 4. Upload bundle to S3: `s3://{EB_BUCKET}/mimir/{VERSION_LABEL}/deploy-bundle.zip` 5. Create EB application version: `aws elasticbeanstalk create-application-version --version-label {VERSION_LABEL} --source-bundle S3Bucket={EB_BUCKET},S3Key=mimir/{VERSION_LABEL}/deploy-bundle.zip` 6. Deploy to idle: `aws elasticbeanstalk update-environment --environment-name {IDLE_ENV} --version-label {VERSION_LABEL}` 7. Smoke test idle, then swap: `aws elasticbeanstalk swap-environment-cnames --source-environment-name {IDLE_ENV} --destination-environment-name {LIVE_ENV}` ``` --- ## Commit (Both Paths) ```bash git add deploy/ git commit -m "feat(deploy): add deployment manifest ({Helm chart\|EB docker-compose template})" ``` --- ## Deliverables (Style-Agnostic) - ✅ Deployment manifest created (Helm chart OR docker-compose template) - ✅ Per-environment values/overrides defined - ✅ Rendering verified (`helm template` OR `envsubst` test) - ✅ `make deploy ENV=<env>` works locally (after Activity #83) ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - SAO.md (Document, Required) — produced by Write SAO.md (#59). - INFRA_REQUIREMENTS.md (Document, Required) — produced by Review SAO & Define Infra Requirements (#74).
#3	Add Container & Deploy Make Targets	Read the 'DCD-3 Add Container & Deploy Make Targets' activity from playbook 'Junior Edda' (workflow 'Design & Deploy CICD'). Follow its guidance when assisting me. # Add Container & Deploy Make Targets ## Objective Extend the application Makefile (from BSP-06) with container, deployment, and operations targets. Uncomment and configure the `##@ Deployment` section in the Makefile template. After this activity, every deployment operation is a single `make` command. --- ## Process ### 1. Add Dockerfile Create a multi-stage Dockerfile in the app monorepo: ```dockerfile # Dockerfile # Stage 1: Build FROM python:3.12-slim AS builder WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . # Stage 2: Runtime FROM python:3.12-slim WORKDIR /app COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages COPY --from=builder /app . EXPOSE 8000 CMD ["gunicorn", "--bind", "0.0.0.0:8000", "{project}.wsgi:application"] ``` ### 2. Uncomment & Configure Makefile Deployment Section In the Makefile (from `BSP/artifacts/makefile_template.mk`), uncomment and configure the `##@ Deployment` section: ```makefile # Add/update these variables at the top PROJECT := {project} AWS_REGION := {region} AWS_ACCOUNT := {account-id} ECR_REPO := $(AWS_ACCOUNT).dkr.ecr.$(AWS_REGION).amazonaws.com/$(PROJECT) HELM_CHART := deploy/helm/$(PROJECT) ENV ?= local NAMESPACE ?= $(ENV) DOMAIN := {domain} IMAGE_TAG := $(shell git rev-parse --short HEAD) ##@ Containers containers: ## Build and push Docker image to ECR @echo "Building container $(ECR_REPO):$(IMAGE_TAG)..." docker build -t $(ECR_REPO):$(IMAGE_TAG) -t $(ECR_REPO):latest . @echo "Pushing to ECR..." aws ecr get-login-password --region $(AWS_REGION) \| docker login --username AWS --password-stdin $(AWS_ACCOUNT).dkr.ecr.$(AWS_REGION).amazonaws.com docker push $(ECR_REPO):$(IMAGE_TAG) docker push $(ECR_REPO):latest @echo "✅ Pushed $(ECR_REPO):$(IMAGE_TAG)" containers-local: ## Build Docker image for local K8s (no push) docker build -t $(PROJECT):local . @echo "✅ Built $(PROJECT):local" ##@ Deployment deploy: ## Deploy to environment (ENV=local\|blue\|green) @echo "Deploying to $(ENV) (namespace: $(NAMESPACE))..." helm upgrade --install $(PROJECT) $(HELM_CHART) \ -f $(HELM_CHART)/values.yaml \ -f $(HELM_CHART)/values-$(ENV).yaml \ --set image.tag=$(IMAGE_TAG) \ --namespace $(NAMESPACE) \ --create-namespace \ --wait --timeout 300s @echo "✅ Deployed to $(ENV)" deploy-local: ## Deploy to local K8s $(MAKE) containers-local $(MAKE) deploy ENV=local deploy-blue: ## Deploy to blue namespace $(MAKE) deploy ENV=blue deploy-green: ## Deploy to green namespace $(MAKE) deploy ENV=green ##@ Traffic & Operations smoke-test: ## Run smoke tests (ENV=blue\|green\|prod) @echo "Running smoke tests on $(ENV)..." $(PYTEST) tests/smoke/ -v --base-url=https://$(ENV).$(DOMAIN) 2>&1 \| tee smoke-tests.log @echo "✅ Smoke tests passed on $(ENV)" switch: ## Switch prod ↔ idle DNS traffic @echo "Switching traffic: prod ↔ idle..." cd ../$(PROJECT)-infra && $(MAKE) traffic-switch @echo "✅ Traffic switched. Verify at https://prod.$(DOMAIN)" rollback: ## Rollback to previous deployment @echo "Rolling back traffic..." cd ../$(PROJECT)-infra && $(MAKE) traffic-rollback @echo "✅ Rolled back" verify: ## Full verification: test + integration + smoke $(MAKE) test $(MAKE) test-integration $(MAKE) smoke-test ENV=$(ENV) @echo "✅ Full verification passed for $(ENV)" pipeline-status: ## Show current deployment status @echo "=== Blue Namespace ===" kubectl get pods -n blue 2>/dev/null \|\| echo " (not deployed)" @echo "=== Green Namespace ===" kubectl get pods -n green 2>/dev/null \|\| echo " (not deployed)" @echo "=== DNS ===" dig +short prod.$(DOMAIN) 2>/dev/null \|\| echo " (not configured)" dig +short idle.$(DOMAIN) 2>/dev/null \|\| echo " (not configured)" ``` ### 3. Verify All New Targets ```bash make help # Should show new sections: Containers, Deployment, Traffic make containers-local # Should build Docker image make deploy-local # Should deploy to local K8s make pipeline-status # Should show pod status ``` ### 4. Test Local End-to-End ```bash # Build and deploy locally make deploy-local # Verify pods running kubectl get pods -n local # Port forward and test kubectl port-forward -n local svc/{project} 8080:80 curl http://localhost:8080/health ``` ### 5. Commit ```bash git add Makefile Dockerfile git commit -m "feat(deploy): add container and deployment make targets" ``` --- ## Deliverables - ✅ Dockerfile created (multi-stage) - ✅ Makefile extended with `containers`, `deploy`, `switch`, `rollback`, `verify`, `pipeline-status` - ✅ `make help` shows new sections - ✅ Local deploy verified (`make deploy-local`) - ✅ All new `make` targets functional ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - Helm Chart Template (Template, Required) — produced by Create Helm Chart & Values (#82). - Makefile Template (Code, Required) — produced by Create Makefile (#93).
#4	Build CI Pipeline	Read the 'DCD-4 Build CI Pipeline' activity from playbook 'Junior Edda' (workflow 'Design & Deploy CICD'). Follow its guidance when assisting me. APPEND TO GUIDANCE: --- ## Release-Gated CI (Huginn Model) For EB / release-gated projects, CI runs on published GitHub Releases (and `workflow_dispatch`), not every push: ```yaml on: release: types: [published] workflow_dispatch: # Push to main → no CI run (intentional — human controls ship via gh release create) ``` Why: Prevents concurrent deploy races (`UpdateEnvironment: Must be Ready`) and gives explicit semver control. ### Dual Registry Build \| Image \| Registry \| Deployed to EB? \| \|-------\|----------\|-----------------\| \| Web app \| ECR (private) \| Yes \| \| MCP facade / CLI tool \| Docker Hub (public) \| No — client-side only \| ### Auth Options \| Method \| When \| \|--------\|------\| \| OIDC `role-to-assume` \| Preferred for org repos \| \| IAM access keys in secrets \| Acceptable for single-team projects \| Do not treat access keys as always wrong — document trade-off in `CICD_REQUIREMENTS.md`.
#5	Build CD Pipeline	Read the 'DCD-5 Build CD Pipeline' activity from playbook 'Junior Edda' (workflow 'Design & Deploy CICD'). Follow its guidance when assisting me. APPEND TO GUIDANCE: --- ## TAF Integration: E2E Staging Gate in CD Add an E2E test stage in the CD pipeline that runs after deploying to the idle/staging environment and before the release/swap: ```yaml e2e-staging: needs: smoke-test runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Python uses: actions/setup-python@v5 - name: Install dependencies run: make provision - name: Install Playwright run: playwright install chromium - name: Run E2E against staging run: make test-e2e BASE_URL=${{ vars.STAGING_URL }} DB_URI=${{ vars.STAGING_DB_URI }} - name: Upload E2E screenshots if: always() uses: actions/upload-artifact@v4 with: name: e2e-screenshots-${{ github.sha }} path: tests/e2e/screenshots/ retention-days: 14 release: needs: e2e-staging ``` ### Pipeline Flow (updated) ``` CI: lint → test-unit → test-integration → test-at → build container → push to ECR CD: deploy-idle → smoke → E2E on staging (screenshots) → release → approve → switch → verify-prod ``` E2E fail → pipeline stops → no release → no swap. Screenshots are always archived for debugging.
#6	Implement Switch & Rollback	Read the 'DCD-6 Implement Switch & Rollback' activity from playbook 'Junior Edda' (workflow 'Design & Deploy CICD'). Follow its guidance when assisting me. # Implement Switch & Rollback ## Objective Ensure traffic switch and rollback work reliably end-to-end. Mechanism depends on deployment style. --- ## Path Selection \| Style \| Switch \| Rollback \| \|-------\|--------\|----------\| \| EKS \| `make switch` → infra `traffic-switch` (Route53 weights) \| `make rollback` → infra `traffic-rollback` \| \| Elastic Beanstalk \| `make swap` → `promote-prod.sh` (CNAME swap) \| Another CNAME swap — previous version still running on other env \| --- ## EKS Path Verify `make switch` and `make rollback` delegate to infra repo. Create `.github/workflows/rollback.yml` with confirmation gate calling `make rollback`. --- ## Elastic Beanstalk Path Skill: AWS EB Blue/Green Deployment ### 1. Verify `make swap` ```makefile swap: ## Promote idle → prod bash scripts/promote-prod.sh ``` Test: deploy to idle → `make swap` → prod `/health/` revision matches. ### 2. EB Rollback = Second Swap No Helm rollback or Route53 weight change. The previously-live env still runs the old image: ```bash # If prod is bad after swap: make swap # swaps back — old env becomes prod again ``` Document: rollback time ≈ CNAME swap + 90s DNS + smoke poll (~3 min max). ### 3. Create `promote.yml` (GitHub) ```yaml name: Promote to Production on: workflow_dispatch: inputs: expected_revision: description: 'Release tag or EB VersionLabel (optional)' required: false jobs: promote: environment: production # approval gate steps: - run: bash scripts/promote-prod.sh env: EB_APP: {project} EB_ENV_A: {project}-prod EB_ENV_B: {project}-idle EXPECTED_REVISION: ${{ inputs.expected_revision }} MIMIR_PROD_URL: https://app.example.com ``` ### 4. Optional Emergency Rollback Workflow `.github/workflows/rollback.yml` — same as promote (another swap), with confirmation input `type "rollback"`. ### 5. Runbook Document in README: - Promote: review idle URL → `gh workflow run promote.yml` or `make swap` - Rollback: `make swap` again (no redeploy needed) - When: smoke fails after promote, user reports, monitoring alerts --- ## Deliverables - ✅ Switch verified for chosen style - ✅ EB: rollback documented as second CNAME swap - ✅ `promote.yml` with production approval gate - ✅ Optional `rollback.yml` with confirmation - ✅ Runbook documented - ✅ Rollback time measured (< 3 min for EB)
#7	End-to-End Pipeline Verification	Read the 'DCD-7 End-to-End Pipeline Verification' activity from playbook 'Junior Edda' (workflow 'Design & Deploy CICD'). Follow its guidance when assisting me. # End-to-End Pipeline Verification ## Objective Ship a test feature through the entire pipeline: code change → CI (test, build) → CD (deploy idle, smoke, approve, switch) → verify production. This is the acceptance gate for the DCD workflow. --- ## Process ### 1. Prepare a Test Feature Make a visible change to verify the full pipeline: ```bash # Add a version endpoint # e.g., GET /version returns {"version": "0.1.0", "commit": "{sha}"} ``` Write tests for it: ```bash # Add test git add . git commit -m "feat: add /version endpoint for pipeline verification" ``` ### 2. Push and Watch CI ```bash git push origin main ``` Monitor GitHub Actions → CI workflow: - ✅ `make provision` — dependencies installed - ✅ `make lint` — no warnings - ✅ `make test` — all tests pass - ✅ `make test-integration` — all pass - ✅ `make containers` — image pushed to ECR Verify image in ECR: ```bash aws ecr describe-images --repository-name {project} \ --query 'imageDetails \| sort_by(@, &imagePushedAt) \| [-1].imageTags' --output text ``` ### 3. Watch CD Pipeline CD triggers automatically after CI succeeds: - ✅ deploy-idle — `make deploy ENV=idle` → pods running in idle namespace - ✅ smoke-test — `make smoke-test ENV=idle` → smoke tests pass Verify idle deployment: ```bash kubectl get pods -n {idle-namespace} curl https://idle.{domain}/version # Should show new version ``` ### 4. Approve Switch In GitHub Actions → CD workflow: - The `switch` job is waiting for approval - Review the smoke test results - Approve in the production environment ### 5. Verify Production After approval: - ✅ `make switch` — DNS weights swapped - ✅ `make smoke-test ENV=prod` — production smoke tests pass ```bash curl https://prod.{domain}/version # Should show new version with current commit SHA ``` ### 6. Test Rollback ```bash # Trigger rollback via GH Actions or CLI make rollback # Verify prod reverted curl https://prod.{domain}/version # Should show previous version # Switch back (re-apply the new version) make switch curl https://prod.{domain}/version # Should show new version again ``` ### 7. Create Verification Checklist Document in `docs/architecture/CICD_VERIFICATION.md`: ```markdown # CI/CD Verification ## Pipeline Summary \| Step \| Status \| Duration \| Notes \| \|------\|--------\|----------\|-------\| \| CI: provision \| ✅ \| ~2 min \| Dependencies cached \| \| CI: lint \| ✅ \| ~30 sec \| Zero warnings \| \| CI: test \| ✅ \| ~1 min \| All pass \| \| CI: test-integration \| ✅ \| ~2 min \| All pass \| \| CI: containers \| ✅ \| ~3 min \| Image: {sha} \| \| CD: deploy-idle \| ✅ \| ~2 min \| Pods healthy \| \| CD: smoke-test \| ✅ \| ~1 min \| All pass \| \| CD: approval \| ✅ \| Manual \| Approved by {user} \| \| CD: switch \| ✅ \| ~60 sec \| DNS propagated \| \| CD: verify-prod \| ✅ \| ~1 min \| All pass \| \| Rollback \| ✅ \| ~60 sec \| DNS reverted \| ## Total Pipeline Time - CI: ~8 min - CD (auto): ~5 min - CD (manual): depends on reviewer - Rollback: ~60 sec ## Make Targets Verified \| Target \| Works Locally \| Works in CI/CD \| \|--------\|--------------\|----------------\| \| make provision \| ✅ \| ✅ \| \| make lint \| ✅ \| ✅ \| \| make test \| ✅ \| ✅ \| \| make containers \| ✅ \| ✅ \| \| make deploy ENV=... \| ✅ \| ✅ \| \| make smoke-test ENV=... \| ✅ \| ✅ \| \| make switch \| ✅ \| ✅ \| \| make rollback \| ✅ \| ✅ \| \| make pipeline-status \| ✅ \| ✅ \| ``` ### 8. Commit ```bash git add docs/architecture/CICD_VERIFICATION.md git commit -m "docs: add CI/CD verification checklist — pipeline fully operational" ``` --- ## Deliverables - ✅ Test feature shipped through full pipeline - ✅ CI pipeline — test → build → push verified - ✅ CD pipeline — deploy idle → smoke → approve → switch verified - ✅ Rollback tested and verified - ✅ `docs/architecture/CICD_VERIFICATION.md` — checklist documented - ✅ Local and CI/CD parity — all `make` targets work identically in both ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - Helm Chart Template (Template, Optional) — produced by Create Helm Chart & Values (#82). - CI Pipeline (GitHub Actions) (Code, Required) — produced by Build CI Pipeline (#84). - CD Pipeline (GitHub Actions) (Code, Required) — produced by Build CD Pipeline (#85).
Bootstrap Project
#1	Verify & Install Prerequisites	Read the 'BSP-1 Verify & Install Prerequisites' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Verify & Install Prerequisites ## Objective Read the Technology Stack Table from `docs/architecture/SAO.md`, check each tool on the developer's machine, install missing tools, and verify all versions meet minimum requirements. Must be idempotent — safe to run repeatedly. --- ## Process ### 1. Detect OS & Package Manager ```bash # Detect OS OS=$(uname -s) # Darwin or Linux # Detect package manager if [[ "$OS" == "Darwin" ]]; then PKG_MGR="brew" # Verify Homebrew is installed command -v brew >/dev/null 2>&1 \|\| { echo "ERROR: Homebrew not found. Install from https://brew.sh" exit 1 } elif [[ -f /etc/debian_version ]]; then PKG_MGR="apt" elif [[ -f /etc/redhat-release ]]; then PKG_MGR="dnf" else echo "ERROR: Unsupported OS. Requires macOS (Homebrew) or Linux (apt/dnf)." exit 1 fi ``` ### 2. Read Technology Stack Table Parse the Technology Stack Table from SAO.md. For each row: 1. Run the Verify Command 2. Compare installed version against Version requirement 3. If missing or below minimum: run the Install Command for the detected OS 4. If already installed and meets minimum: skip with ✅ message ### 3. Install Logic (Idempotent) For each tool in the stack table: ```bash check_and_install() { local tool="$1" local min_version="$2" local verify_cmd="$3" local install_cmd="$4" if eval "$verify_cmd" >/dev/null 2>&1; then local current_version=$(eval "$verify_cmd" 2>&1 \| grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?') echo "✅ $tool $current_version (required: $min_version)" else echo "📦 Installing $tool..." eval "$install_cmd" if eval "$verify_cmd" >/dev/null 2>&1; then echo "✅ $tool installed successfully" else echo "❌ Failed to install $tool" exit 1 fi fi } ``` ### 4. Post-Install Verification After all tools are installed, run a summary check: ``` Prerequisites Check Summary: Python 3.12.4 ✅ (required: 3.12+) Django 5.1.2 ✅ (required: 5.1+) Node.js 20.11.0 ✅ (required: 20+) npm 10.2.4 ✅ (required: 10+) git 2.43.0 ✅ (required: 2.x) make 4.4.1 ✅ (required: 4+) ruff 0.6.3 ✅ (required: 0.6+) pytest 8.3.1 ✅ (required: 8+) ... All prerequisites satisfied. ✅ ``` ### 5. Handle Edge Cases - Homebrew not installed: Error with install instructions, do not auto-install Homebrew - Permission errors: Suggest `sudo` for system-level packages on Linux - Version conflicts: Warn if installed version is newer than specified (should be fine) or if it's a different major version - Python virtual environment: Do NOT create venv here — that's BSP-04's job - npm global packages: Prefer local (npx) over global installs where possible --- ## Deliverables - ✅ OS & package manager detected - ✅ All tools from Technology Stack Table verified or installed - ✅ Version requirements met for all tools - ✅ Summary report printed - ✅ Idempotent — safe to re-run
#2	Initialize Repository	Read the 'BSP-2 Initialize Repository' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Initialize Repository ## Objective Create a new Git repository with essential root-level files: `.gitignore`, `README.md`, `LICENSE`, and initial commit. --- ## Process ### 1. Initialize Git ```bash git init git branch -M main ``` ### 2. Create .gitignore Generate a `.gitignore` tailored to the technology stack from SAO.md. Include patterns for: ```gitignore # Python __pycache__/ .py[cod] $py.class .egg-info/ dist/ build/ .venv/ venv/ .egg # Node.js node_modules/ npm-debug.log* # IDE .vscode/ .idea/ .swp .swo ~ # OS .DS_Store Thumbs.db # Environment .env .env.local .env..local # Database .sqlite3 db.sqlite3 # Logs logs/ .log # Coverage htmlcov/ .coverage .coverage.* coverage.xml # Build artifacts staticfiles/ media/ ``` Adapt based on actual stack decisions in SAO.md. ### 3. Create README.md ```markdown # {Project Name} {One-sentence description from ESM user journey} ## Quick Start \`\`\`bash make provision # Install prerequisites & dependencies make run # Start development server \`\`\` Then open http://localhost:8000 in your browser. ## Development \| Command \| Description \| \|------------------\|--------------------------------\| \| `make provision` \| Install all prerequisites \| \| `make run` \| Start development server \| \| `make test` \| Run all tests \| \| `make lint` \| Run linter \| \| `make format` \| Auto-format code \| \| `make clean` \| Remove build artifacts \| \| `make help` \| Show all available targets \| ## Documentation - [System Architecture Overview](docs/architecture/SAO.md) - [Modus Operandi](docs/process/MODUS_OPERANDI.md) ``` ### 4. Create LICENSE Choose license based on project requirements. Default to MIT unless SAO.md specifies otherwise. ### 5. Initial Commit ```bash git add . git commit -m "chore(init): initialize repository with .gitignore, README, LICENSE" ``` --- ## Deliverables - ✅ Git repository initialized on `main` branch - ✅ .gitignore created for project stack - ✅ README.md with Quick Start and Makefile target table - ✅ LICENSE file created - ✅ Initial commit made ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - Makefile Template (Code, Required) — produced by Create Makefile (#93).
#3	Scaffold Project Structure	Read the 'BSP-3 Scaffold Project Structure' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Scaffold Project Structure ## Objective Create the directory tree as defined in DTA-04 (Code Organization). This includes all top-level directories, app directories, placeholder files, and `__init__.py` files where needed. --- ## Process ### 1. Read DTA-04 Decisions From SAO.md § Code Organization, extract: - Repository strategy (monorepo/polyrepo) - Directory structure with layer separation - App/module names from DTA-02 (Application Blocks) ### 2. Create Directory Tree Example for a Django project: ```bash mkdir -p {app_name}/{models,services,views,templates/{app_name}} mkdir -p tests/{unit,integration,e2e} mkdir -p docs/{architecture,process,features,ux,runbooks} mkdir -p logs mkdir -p static/{css,js,img} mkdir -p scripts ``` ### 3. Create Placeholder Files For each directory, create the minimum files needed so the structure is functional: ```bash # Python packages need __init__.py touch {app_name}/__init__.py touch {app_name}/models/__init__.py touch {app_name}/services/__init__.py touch {app_name}/views/__init__.py touch tests/__init__.py touch tests/unit/__init__.py touch tests/integration/__init__.py touch tests/e2e/__init__.py # Keep empty directories in Git touch logs/.gitkeep touch static/css/.gitkeep touch static/js/.gitkeep touch static/img/.gitkeep touch docs/runbooks/.gitkeep ``` ### 4. Create docs/ Placeholder Structure ```bash # Architecture docs (from DTA) touch docs/architecture/.gitkeep # Process docs (from DSP) touch docs/process/.gitkeep # Feature files (from ESM) touch docs/features/.gitkeep # UX artifacts (from ESM) touch docs/ux/.gitkeep ``` ### 5. Commit Scaffold ```bash git add . git commit -m "chore(scaffold): create project directory structure per DTA-04" ``` --- ## Deliverables - ✅ Directory tree created per DTA-04 decisions - ✅ App packages initialized with `__init__.py` - ✅ Test directory structure created (unit/integration/e2e) - ✅ Docs directory structure created - ✅ Static assets directories created - ✅ Scaffold committed ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - IA Guidelines (Document, Required) — produced by Define Information Architecture (#37). - System Architecture Overview Template (Template, Required) — produced by Write SAO.md (#59). - Makefile Template (Code, Required) — produced by Create Makefile (#93).
#4	Initialize Runtimes & Dependencies	Read the 'BSP-4 Initialize Runtimes & Dependencies' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Initialize Runtimes & Dependencies ## Objective Set up language runtimes (Python venv, Node.js) and install project dependencies via their respective package managers. Create dependency manifest files (`requirements.txt`, `package.json`) with pinned versions from the SAO.md Technology Stack Table. --- ## Process ### 1. Python Runtime ```bash # Create virtual environment python3 -m venv .venv # Activate (for current session) source .venv/bin/activate # Upgrade pip pip install --upgrade pip # Create requirements.txt from SAO.md Technology Stack Table cat > requirements.txt << 'EOF' # Core framework django>=5.1,<6.0 # Testing pytest>=8.0 pytest-django>=4.8 # Code quality ruff>=0.6 # Logging # (add based on DTA-12 Observability decisions) # Add all Python dependencies from SAO.md stack table here EOF # Install pip install -r requirements.txt ``` ### 2. Django Project Initialization (if Django is chosen) ```bash # Create Django project (only if manage.py doesn't exist) django-admin startproject config . # This creates: # config/ # ├── __init__.py # ├── settings.py # ├── urls.py # ├── asgi.py # └── wsgi.py # manage.py ``` Adjust `config/settings.py`: - Set `ALLOWED_HOSTS` - Configure `DATABASES` per DTA-05 decisions - Configure `STATIC_URL`, `STATICFILES_DIRS` - Configure logging per DTA-12 decisions - Set `SECRET_KEY` handling per DTA-13 decisions ### 3. Node.js Runtime (if applicable) ```bash # Initialize package.json npm init -y # Install frontend dependencies from SAO.md npm install --save-dev \ playwright \ # Add based on stack decisions # Create .nvmrc for Node version pinning echo "20" > .nvmrc ``` ### 4. Pytest Configuration Create `pytest.ini` or add to `pyproject.toml`: ```ini [tool.pytest.ini_options] DJANGO_SETTINGS_MODULE = "config.settings" python_files = ["tests.py", "test_.py", "_tests.py"] python_paths = ["."] addopts = "-v --tb=short" log_cli = true log_file = "tests.log" log_file_level = "INFO" ``` ### 5. Create pyproject.toml (if not exists) Consolidate Python tool configuration: ```toml [project] name = "{project-name}" version = "0.1.0" requires-python = ">=3.12" [tool.ruff] line-length = 120 target-version = "py312" [tool.ruff.lint] select = ["E", "F", "I", "N", "W"] [tool.pytest.ini_options] DJANGO_SETTINGS_MODULE = "config.settings" addopts = "-v --tb=short" log_file = "tests.log" ``` ### 6. Commit Dependencies ```bash git add . git commit -m "chore(deps): initialize Python venv, requirements.txt, Django project, pytest config" ``` --- ## Deliverables - ✅ Python venv created at `.venv/` - ✅ requirements.txt created with pinned versions from SAO.md - ✅ Django project initialized (if applicable) - ✅ package.json created (if Node.js in stack) - ✅ pyproject.toml created with tool configuration - ✅ All dependencies installed and verified - ✅ Dependencies committed ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - System Architecture Overview Template (Template, Required) — produced by Write SAO.md (#59). - Makefile Template (Code, Required) — produced by Create Makefile (#93).
#5	Configure Dev Tooling	Read the 'BSP-5 Configure Dev Tooling' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Configure Dev Tooling ## Objective Set up linters, formatters, pre-commit hooks, IDE settings, and debug configurations as defined in DTA-16 (Developer Experience). --- ## Process ### 1. Pre-commit Hooks ```bash # Install pre-commit pip install pre-commit # Create .pre-commit-config.yaml cat > .pre-commit-config.yaml << 'EOF' repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.6.0 hooks: - id: ruff args: [--fix] - id: ruff-format - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.6.0 hooks: - id: trailing-whitespace - id: end-of-file-fixer - id: check-yaml - id: check-added-large-files - id: check-merge-conflict EOF # Install hooks pre-commit install ``` ### 2. IDE Settings (VS Code / Windsurf / Cursor) ```bash mkdir -p .vscode # Settings cat > .vscode/settings.json << 'EOF' { "python.defaultInterpreterPath": ".venv/bin/python", "python.analysis.typeCheckingMode": "basic", "[python]": { "editor.defaultFormatter": "charliermarsh.ruff", "editor.formatOnSave": true, "editor.codeActionsOnSave": { "source.fixAll": "explicit", "source.organizeImports": "explicit" } }, "files.exclude": { "/__pycache__": true, "/.pyc": true, ".venv": true, "node_modules": true }, "editor.rulers": [120] } EOF # Extensions recommendations cat > .vscode/extensions.json << 'EOF' { "recommendations": [ "charliermarsh.ruff", "ms-python.python", "ms-python.debugpy", "batisteo.vscode-django", "firefox-devtools.vscode-firefox-debug" ] } EOF ``` ### 3. Debug Configurations ```bash cat > .vscode/launch.json << 'EOF' { "version": "0.2.0", "configurations": [ { "name": "Django: Run Server", "type": "debugpy", "request": "launch", "program": "${workspaceFolder}/manage.py", "args": ["runserver", "0.0.0.0:8000"], "django": true, "justMyCode": false }, { "name": "Pytest: Current File", "type": "debugpy", "request": "launch", "module": "pytest", "args": ["${file}", "-v", "--tb=short"], "justMyCode": false }, { "name": "Pytest: All Tests", "type": "debugpy", "request": "launch", "module": "pytest", "args": ["tests/", "-v", "--tb=short"], "justMyCode": false } ] } EOF ``` ### 4. EditorConfig ```bash cat > .editorconfig << 'EOF' root = true [] indent_style = space indent_size = 4 end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true [.{js,jsx,ts,tsx,json,yml,yaml,html,css}] indent_size = 2 [Makefile] indent_style = tab EOF ``` ### 5. Commit Tooling Config ```bash git add . git commit -m "chore(tooling): configure linter, formatter, pre-commit, IDE settings, debug configs" ``` --- ## Deliverables - ✅ Pre-commit hooks* installed and configured - ✅ VS Code settings configured (formatter, linter, interpreter) - ✅ Debug configurations created (Django server, pytest) - ✅ EditorConfig created for consistent formatting - ✅ IDE extension recommendations added - ✅ Tooling committed ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - System Architecture Overview Template (Template, Required) — produced by Write SAO.md (#59). - Makefile Template (Code, Required) — produced by Create Makefile (#93).
#6	Create Makefile	Read the 'BSP-6 Create Makefile' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Create Makefile ## Objective Create a comprehensive Makefile that serves as the single orchestration layer for all development, infrastructure, and deployment operations. CI/CD pipelines call these targets — no business logic lives in GitHub Actions. The Makefile template is in `BSP/artifacts/makefile_template.mk`. Copy it, adapt variables to your stack, and verify all targets work. --- ## Process ### 1. Copy Makefile Template Copy `BSP/artifacts/makefile_template.mk` to your project root as `Makefile`. The template includes: - Base sections: General, Provision, Development, Testing, Code Quality, Database, Cleanup - Extension points: `##@ Infrastructure` and `##@ Deployment` sections (commented out, added by DCI/DCD workflows later) - Commented variable blocks for infra and deployment (uncommented during DCI/DCD) See the full template: [`BSP/artifacts/makefile_template.mk`](artifacts/makefile_template.mk) ### 2. Adapt to Stack - Read SAO.md Technology Stack Table for tool paths and versions - If no Node.js in stack: remove `_npm-install` and `package.json` check - If no Django: replace `manage.py` commands with framework equivalents - If additional tools (e.g., Docker): add `docker-up`, `docker-down` targets - All targets should follow the pattern: verb-noun (e.g., `test-unit`, `db-init`) - Do NOT uncomment `##@ Infrastructure` or `##@ Deployment` sections yet — those are added by DCI and DCD workflows respectively ### 3. Verify All Targets Run each target and verify it works: ```bash make help # Should show formatted help make provision # Should complete without errors make lint # Should run (may report issues — that's OK) make format # Should run make test # Should run (may have 0 tests — that's OK) make clean # Should clean up ``` ### 4. Commit Makefile ```bash git add Makefile git commit -m "chore(make): create Makefile with provision, run, test, lint, format, clean targets" ``` --- ## Deliverables - ✅ Makefile created with all standard targets - ✅ `make help` shows all targets with descriptions - ✅ `make provision` installs everything from scratch - ✅ All targets verified as functional - ✅ Makefile committed
#7	Create Welcome Page & Verify	Read the 'BSP-7 Create Welcome Page & Verify' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Create Welcome Page & Verify ## Objective Create a basic health-check welcome page that displays application health status, verify `make provision` works end-to-end, and confirm F5 (debug launch) shows the welcome page in the browser. --- ## Process ### 1. Create Health Check View Create a simple view that shows system health: ```python # {app}/views/health.py import sys import django import platform from datetime import datetime from django.http import JsonResponse from django.shortcuts import render def health_json(request): """JSON health endpoint for monitoring.""" return JsonResponse({ "status": "healthy", "timestamp": datetime.utcnow().isoformat(), "python_version": sys.version, "django_version": django.__version__, "platform": platform.platform(), }) def welcome(request): """Welcome page showing app health dashboard.""" context = { "status": "healthy", "timestamp": datetime.now(), "python_version": sys.version.split()[0], "django_version": django.__version__, "platform": platform.platform(), "checks": _run_health_checks(), } return render(request, "welcome.html", context) def _run_health_checks(): """Run basic health checks and return results.""" checks = [] # Database check try: from django.db import connection connection.ensure_connection() checks.append({"name": "Database", "status": "✅", "detail": "Connected"}) except Exception as e: checks.append({"name": "Database", "status": "❌", "detail": str(e)}) # Static files check import os static_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "static") if os.path.isdir(static_dir): checks.append({"name": "Static Files", "status": "✅", "detail": "Directory exists"}) else: checks.append({"name": "Static Files", "status": "⚠️", "detail": "Directory missing"}) # Logging check log_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "logs") if os.path.isdir(log_dir): checks.append({"name": "Logging", "status": "✅", "detail": "Log directory exists"}) else: checks.append({"name": "Logging", "status": "⚠️", "detail": "Log directory missing"}) return checks ``` ### 2. Create Welcome Template ```html <!-- templates/welcome.html --> <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>{{ project_name }} — Welcome</title> <style> /* Minimal inline CSS — no external dependencies needed at bootstrap / body { font-family: -apple-system, system-ui, sans-serif; max-width: 800px; margin: 40px auto; padding: 0 20px; color: #333; } h1 { color: #2563eb; } .status { display: inline-block; padding: 4px 12px; border-radius: 12px; font-size: 14px; font-weight: 600; } .status.healthy { background: #dcfce7; color: #166534; } .checks { margin-top: 20px; } .check { display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #e5e7eb; } .meta { color: #6b7280; font-size: 14px; margin-top: 20px; } table { width: 100%; border-collapse: collapse; margin-top: 12px; } td, th { text-align: left; padding: 8px; border-bottom: 1px solid #e5e7eb; } </style> </head> <body> <h1>🚀 {{ project_name }}</h1> <p>Application is running. <span class="status healthy">{{ status }}</span></p> <h2>Health Checks</h2> <table> <tr><th>Component</th><th>Status</th><th>Detail</th></tr> {% for check in checks %} <tr> <td>{{ check.name }}</td> <td>{{ check.status }}</td> <td>{{ check.detail }}</td> </tr> {% endfor %} </table> <div class="meta"> <p>Python {{ python_version }} · Django {{ django_version }}</p> <p>{{ platform }}</p> <p>{{ timestamp }}</p> </div> </body> </html> ``` ### 3. Wire Up URLs ```python # config/urls.py from django.urls import path from {app}.views.health import welcome, health_json urlpatterns = [ path("", welcome, name="welcome"), path("health/", health_json, name="health-json"), ] ``` ### 4. End-to-End Verification Run the full bootstrap sequence and verify: ```bash # 1. Provision from scratch make provision # Expected: all dependencies installed, DB migrated, no errors # 2. Run the server make run # Expected: Django dev server starts on http://localhost:8000 # 3. Verify welcome page # Open http://localhost:8000 in browser # Expected: Welcome page showing "healthy" status with all checks ✅ # 4. Verify health JSON endpoint curl http://localhost:8000/health/ # Expected: {"status": "healthy", "python_version": "...", ...} # 5. Verify F5 debug launch # Press F5 in IDE → Django server starts under debugger # Breakpoints work, can inspect variables # 6. Run tests (should pass even if 0 tests) make test # Expected: no failures # 7. Run linter make lint # Expected: clean or only style warnings ``` ### 5. Final Commit ```bash git add . git commit -m "feat(bootstrap): add welcome page with health checks, wire up URLs Bootstrap verification complete: - make provision ✅ - make run ✅ - F5 debug launch ✅ - Welcome page at / with health dashboard - JSON health endpoint at /health/" ``` --- ## Deliverables - ✅ Welcome page* showing app health status at `/` - ✅ Health JSON endpoint at `/health/` - ✅ `make provision` completes without errors - ✅ `make run` starts server, welcome page visible - ✅ F5 debug launch works in IDE - ✅ `make test` runs without failures - ✅ `make lint` runs cleanly - ✅ Final commit with verification results
#8	Configure Observability & Logging	Read the 'BSP-8 Configure Observability & Logging' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Configure Observability & Logging ## Objective Set up three-tier logging infrastructure for backend operations (`logs/app.log`), frontend interactions (`logs/gui.log`), and AI token consumption (`logs/consumption.log`). This provides observability from day one and enables EST workflow token tracking for estimate calibration. --- ## Prerequisites - BSP-07 complete (welcome page verified) - Project structure exists - Django settings configured - Static files directory exists --- ## Goals ### Goal 1: Backend Operation Logging What: All backend operations log to `logs/app.log` with informative context Why: Enable troubleshooting without reproduction by logging who, what, where, when, and why for every significant operation Success Criteria: - [ ] Django LOGGING configuration added to settings - [ ] RotatingFileHandler configured (10MB, 5 backups) - [ ] Log format includes module, function, line number, and context - [ ] All service methods log entry, exit, and errors - [ ] Log messages follow informative logging pattern (who, what, where, when, why) Implementation: See Skill Django Logging Setup --- ### Goal 2: Frontend Interaction Logging What: All HTMX interactions and user actions log to `logs/gui.log` Why: Track user behavior, debug frontend issues, and understand interaction patterns Success Criteria: - [ ] JavaScript Logger class created in `static/js/logger.js` - [ ] HTMX event listeners configured (beforeRequest, afterRequest, responseError) - [ ] Django backend endpoint created (`/api/log/gui/`) - [ ] Frontend logs sent to backend for persistence - [ ] Console integration for development debugging Implementation: See Skill HTMX Frontend Logging --- ### Goal 3: Token Consumption Tracking What: AI token usage logged to `logs/consumption.log` in JSON format Why: Enable EST workflow sprint-by-sprint calibration via velocity factor calculation and K-token baseline updates Success Criteria: - [ ] TokenTracker utility class created - [ ] Scenario-level token tracking implemented - [ ] JSON log format compatible with EST-08 Sprint Close & Rebaseline - [ ] Consumption logger configured with JSON formatter - [ ] Sprint report generation utility available Implementation: See Skill Claude Token Tracking --- ## Implementation Steps ### Step 1: Create Logs Directory Structure ```bash mkdir -p logs touch logs/.gitkeep # Add logs to .gitignore (keep structure, ignore content) cat >> .gitignore << 'EOF' # Logs logs/.log !logs/.gitkeep EOF ``` Deliverable: `logs/` directory with `.gitkeep`, `.gitignore` updated --- ### Step 2: Configure Backend Logging Objective: Add Django LOGGING configuration for three log files Tasks: 1. Add LOGGING dictionary to `{project_name}/settings.py` 2. Configure formatters (verbose, simple, json) 3. Configure handlers (app_file, gui_file, consumption_file, console) 4. Configure loggers (django, {project_name}, gui, consumption) 5. Add informative logging to service methods Reference: See Skill Django Logging Setup* for: - Complete LOGGING configuration - RotatingFileHandler setup - Logger usage patterns in services, views, models - Informative logging message format - Testing logging configuration Deliverable: Django LOGGING configured, backend operations logging to `app.log` --- ### Step 3: Configure Frontend Logging Objective: Create JavaScript logger and backend endpoint for GUI events Tasks: 1. Create `static/js/logger.js` with Logger class 2. Add HTMX event listeners (beforeRequest, afterRequest, responseError, etc.) 3. Create Django view `{app_name}/views/logging_views.py::log_gui_event` 4. Add URL route `/api/log/gui/` 5. Include logger in `templates/base.html` 6. Test frontend logging in browser console Reference: See Skill HTMX Frontend Logging for: - JavaScript Logger class implementation - HTMX event logging patterns - Django backend endpoint - User action logging - JavaScript error catching - Performance considerations (throttling, batching) Deliverable: Frontend interactions logging to `gui.log` --- ### Step 4: Configure Token Consumption Tracking Objective: Create TokenTracker utility for EST workflow integration Tasks: 1. Create `{app_name}/utils/token_tracker.py` with TokenTracker class 2. Add consumption logger to Django settings (JSON formatter) 3. Create utility functions for parsing consumption.log 4. Create Django management command for sprint reports 5. Document integration with BPE workflow Reference: See Skill Claude Token Tracking for: - TokenTracker class implementation - JSON log format for EST-08 - Parsing and aggregation utilities - Sprint report generation - Integration with Claude API - Velocity factor calculation Deliverable: Token consumption logging to `consumption.log` in EST-compatible format --- ### Step 5: Verify All Logs Are Working Verification Checklist: 1. Backend Logging: ```bash # Start Django server python manage.py runserver # Trigger some operations (create, read, update) # Check logs/app.log for entries tail -f logs/app.log ``` 2. Frontend Logging: ```bash # Open browser to http://localhost:8000 # Open browser console (F12) # Click buttons, submit forms # Verify console shows log messages # Check logs/gui.log for persisted entries tail -f logs/gui.log ``` 3. Token Consumption: ```python # In Django shell from {app_name}.utils.token_tracker import log_token_consumption log_token_consumption( scenario_id="TEST-01", user_id=1, tokens_used=1000, model="claude-3-5-sonnet-20241022", sprint=1 ) ``` ```bash # Check logs/consumption.log cat logs/consumption.log # Should show JSON entry ``` 4. Log Rotation: ```bash # Verify file size limits ls -lh logs/ # Should show maxBytes=10MB configured ``` Deliverable: All three logs verified and working --- ### Step 6: Commit Logging Infrastructure ```bash git add logs/.gitkeep .gitignore git add {project_name}/settings.py git add static/js/logger.js git add {app_name}/views/logging_views.py git add {app_name}/utils/token_tracker.py git add {app_name}/urls.py git add templates/base.html git commit -m "feat(observability): configure three-tier logging infrastructure Add comprehensive logging for backend operations, frontend interactions, and AI token consumption: Backend (logs/app.log): - Django LOGGING configuration with RotatingFileHandler - Informative logging pattern (module:function:line + context) - Logs for services, views, models, and signals Frontend (logs/gui.log): - JavaScript Logger class with console and backend integration - HTMX event listeners for all interactions - Django endpoint for GUI log collection - User action and error logging Token Consumption (logs/consumption.log): - TokenTracker utility for scenario-level tracking - JSON format compatible with EST-08 Sprint Close workflow - Parsing and aggregation utilities - Sprint report generation command Enables: - Troubleshooting without reproduction - User behavior analysis - EST workflow token calibration Refs: Activity EST-08 (Sprint Close and Rebaseline)" ``` Deliverable: Logging infrastructure committed to repository --- ## Success Criteria - [x] Logs directory created with `.gitkeep` - [x] `.gitignore` updated to exclude `logs/.log` - [x] Backend logging* configured in Django settings - [x] app.log receiving backend operation logs - [x] gui.log receiving frontend interaction logs - [x] consumption.log receiving token consumption in JSON format - [x] Log rotation configured (10MB, 5 backups) - [x] Informative logging pattern followed (module:function:line + context) - [x] JavaScript Logger created and included in base template - [x] HTMX events automatically logged - [x] TokenTracker utility created - [x] All logs verified and working - [x] Infrastructure committed to repository --- ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - System Architecture Overview Template (Template, Required) — produced by Write SAO.md (#59). - Makefile Template (Code, Required) — produced by Create Makefile (#93). ## Construction Handoff BSP is the final Elaboration workflow. Before starting Construction, verify all four gates: \| Gate \| Artifact \| Workflow if missing \| \|------\|----------\|---------------------\| \| ESM \| `docs/features/user_journey.md` + `.feature` files in `docs/features/act-/` \| ESM — Envision the System \| \| DTA \| `docs/architecture/SAO.md` \| DTA — Define Architecture \| \| DSP \| `CLAUDE.md` \| DSP — Deploy Software Process \| \| BSP \| `Makefile` + `requirements.txt` \| this workflow (BSP) \| \| SAO §17 (if applicable) \| `tests/support/agent_story.py` \| TFK-02 — Bootstrap Test Harness \| If any gate fails, run that workflow and return here. When all gates pass, choose your Construction mode: Option A — Feature-by-feature (BPE)* Use when: scope is still fuzzy, building one feature at a time, or human review on every plan is preferred. → Run BPE on a single `.feature` spec. Option B — Dark factory (PIN → MIN) Use when: a full act is defined with multiple ready scenarios and autonomous milestone execution is wanted. → Run PIN with a goal sentence (e.g. "we aim to complete act-1"). After PIN-05 human GO, say `Work on Milestone #N` to activate MIN. Heuristic: Run BPE for your first feature to validate the setup end-to-end. Once the pattern is confirmed, switch to PIN → MIN for subsequent acts. BPE is the build engine in both modes — PIN-03 runs BPE-01 per scenario; MIN-04 runs BPE-02–05. Do not run BPE in a manual loop to approximate Option B. DCD (Design & Deploy CI/CD) is not required to start building. Deploy when 0.1 is ready.
Test Automation Framework
#2	Bootstrap Test Harness	Read the 'TFK-2 Bootstrap Test Harness' activity from playbook 'Junior Edda' (workflow 'Test Automation Framework'). Follow its guidance when assisting me. # Bootstrap Test Harness ## Objective Set up the complete test infrastructure: directory structure, pytest configuration, behave-django configuration, Playwright integration, Makefile targets, continuous test runner, and the Log Story helper (`tests/support/log_story.py`) used by BPE/MIN caplog gates. Layout rule: AT scenarios live in `docs/features/` (spec + runner — single source of truth). There is no separate `tests/acceptance/` or `features/at/` tree. E2E is a standalone suite under `tests/e2e/` with its own `environment.py` and Playwright-backed steps. --- ## Process ### 1. Create Test Directory Structure ``` tests/ ├── unit/ # pytest -m unit │ └── conftest.py ├── integration/ # pytest -m integration │ └── conftest.py ├── integration/agent/ # pytest -m agent_proof (lane 1) │ └── test_prf_.py ├── e2e/ # behave + Playwright (E2E) │ ├── .feature # journey scenarios │ ├── steps/ # Playwright-backed steps (same Gherkin phrases as AT) │ └── environment.py # LiveServer + browser + screenshots ├── infra/ # CDK assertion tests ├── fixtures/ # Shared fixture data │ ├── seed.json │ ├── presets/ │ ├── llm_scripts/ # Ordered ScriptedLLM queues per PRF-* (lane 1) │ │ └── <prf-id>/ │ │ ├── happy.json │ │ └── reject_.json │ └── agent_tasks/ # Frozen TASK- corpora + oracle YAML (lane 4) │ └── <task-id>/ │ ├── input/ │ ├── expected.yaml │ └── meta.yaml ├── support/ # Shared pytest helpers │ ├── __init__.py │ ├── log_story.py # assert_log_story(caplog, where=..., beats=...) │ └── agent_story.py # assert_agent_story(trace, workflow=..., beats=...) └── conftest.py docs/features/ # BDD spec + AT runner (behave.ini paths = docs/features) ├── act-/ # .feature files per act ├── steps/ # AT Step Library (Django test client) ├── support/ # page registry └── environment.py # behave-django AT lifecycle (atomic rollback) ``` Document the log-story helper import path in root `tests/conftest.py` so BPE/MIN agents discover it. Recipes: skill Pytest Log Story Assertions* (`LOG_STORY_TESTING`). Log-story tests run inside existing `make test` / pytest — no new CI job. When SAO §17 applies, also document `assert_agent_story` import path and the `scripted_llm` / `agent_harness` fixtures (skill Agent Integration Proof Patterns). Agent-proof tests use the existing pytest runner gated by `make test-agent-proof` — no change to default `ci.yml` until PRF tests exist. ### Helper contract ```python def assert_log_story( caplog, , where: str, beats: dict[str, list[str]], level: str = "INFO", ) -> None: """Fail with which beat/key was missing; do not swallow AssertionError.""" ``` ### 2. Configure pytest ```ini [pytest] DJANGO_SETTINGS_MODULE = {project}.settings python_files = test_.py python_classes = Test* python_functions = test_* testpaths = tests addopts = -v --strict-markers --tb=short --log-file=tests.log --log-file-level=INFO markers = unit: Unit tests (fast, isolated) integration: Integration tests (real deps, no mocking) acceptance: Acceptance tests (behave BDD) e2e: End-to-end tests (Playwright, excluded from default runs) slow: Slow running tests agent_proof: Lane 1 control-plane proofs (ScriptedLLM, real DB/tools) live_llm: Lane 3 live provider contract eval (excluded from default PR run) quality: Lane 4 TASK-* golden quality eval (promotion band, not PR gate) ``` Default `make test` / `pytest` collection MUST exclude `live_llm` and `quality` (and `agent_proof` until `AGENTS_ENABLED=true` — see TFK-05). Do not add `-m agent_proof` to bare PR CI until at least one PRF test exists (empty marker selection fails). ### 3. Configure behave ```ini # behave.ini [behave] paths = docs/features format = pretty logging_level = INFO tags = ~@wip ``` Create `docs/features/environment.py` (AT: Django test client / atomic fixtures) and `tests/e2e/environment.py` (E2E: Playwright + LiveServer) separately — engines differ; do not share one environment for both. Makefile: - `make test-at` → `manage.py behave --simple docs/features/` - `make test-e2e` → `manage.py behave tests/e2e/` - `make test-agent-proof` → gated `pytest -m agent_proof` when `AGENTS_ENABLED=true` (TFK-05) ### 4. Configure Playwright Integration For E2E tests using behave + Playwright with LiveServerTestCase under `tests/e2e/`. ### 5. Agent story harness When SAO §17 applies, ship `tests/support/agent_story.py` alongside `log_story.py`. Rule: `do-assert-agent-story`. Skill: Agent Integration Proof Patterns. Helper contract: ```python def assert_agent_story( trace, , workflow: str, beats: dict[str, list[str]], ) -> None: """Fail naming missing beat; trace from agent run recorder (not caplog).""" ``` Fixtures (root `tests/conftest.py` or `tests/integration/agent/conftest.py`):* ```python @pytest.fixture def scripted_llm(prf_id): """Load ordered queue from tests/fixtures/llm_scripts/<prf-id>/happy.json.""" return ScriptedLLM(load_script(f"tests/fixtures/llm_scripts/{prf_id}/")) @pytest.fixture def agent_harness(db): """Real DB, real tool registry, CAP-004 injectable LLM — no domain mocks.""" ... ``` Test naming: `test_<prf>_agent_story_happy` / `test_<prf>_agent_story_reject` when the PRF row is adverse or has a reject sketch. Markers: \| Marker \| Lane \| LLM \| CI \| \|--------\|------\|-----\|-----\| \| `agent_proof` \| 1 \| ScriptedLLM only \| PR when `AGENTS_ENABLED=true` \| \| `live_llm` \| 3 \| Live provider, temp=0 \| Nightly `agent-eval.yml` \| \| `quality` \| 4 \| Live provider, temp=0 \| Promotion band \| Agent-story tests prove control-plane trace beats; log-story tests prove logging beats — complementary, both green in the same commit when declared (see rule `do-assert-log-story`). ## Rules Before bootstrapping the harness, read each Rule below in this playbook (by slug), then apply it. Do not rely on memory of the rule text. Required: - `pytest` - `do-continuous-testing` - `do-assert-log-story` - `do-informative-logging` - `do-test-fixture-data-management` When SAO §17 applies, also required: - `do-assert-agent-story` Activity-specific (not a substitute for the rules above): - Ship `tests/support/log_story.py` (`assert_log_story`) as part of harness bootstrap; log-story tests use the existing pytest runner (no new CI job). - Ship `tests/support/agent_story.py` (`assert_agent_story`) when §17 applies; agent-proof tests use gated `make test-agent-proof` (no change to default PR job until tests exist). ## Success Criteria - Directory layout matches Process §1 (including `tests/support/log_story.py`) - pytest and behave configured - At least one golden `_log_story_` test can import and use `assert_log_story` - When SAO §17 applies: directory layout includes `agent_story.py`, `llm_scripts/`, `agent_tasks/`; pytest markers `agent_proof`, `live_llm`, `quality` registered; at least one golden `test_*_agent_story_happy` imports `assert_agent_story` and runs green under ScriptedLLM
#3	Build Step Library	Read the 'TFK-3 Build Step Library' activity from playbook 'Junior Edda' (workflow 'Test Automation Framework'). Follow its guidance when assisting me. # Build Step Library ## Objective Create a reusable library of Gherkin step definitions that ESM can compose scenarios from when the library already exists. The library grows over time — initial seed covers generic patterns, project-specific steps are added via TFK-07 as needed. Same phrases, different engines: AT steps in `docs/features/steps/` use the Django test client. E2E counterparts in `tests/e2e/steps/` use Playwright. Gherkin vocabulary is shared via the Step Library Catalog; implementations are not merged into one module. --- ## Process ### 1. Organize Steps by Domain ``` docs/features/steps/ # AT — Django test client ├── navigation_steps.py ├── form_steps.py ├── table_steps.py ├── auth_steps.py ├── assertion_steps.py ├── dialog_steps.py ├── common_steps.py └── __init__.py tests/e2e/steps/ # E2E — Playwright-backed counterparts ``` ### 2. Generic Step Patterns Navigation: - `Given {user} is on the "{page_name}" page` - `When {user} navigates to "{url}"` - `Then {user} should see the "{page_name}" page` Forms: - `When {user} enters "{value}" into "{field}"` - `When {user} selects "{option}" from "{dropdown}"` - `When {user} clicks "{button}"` - `When {user} submits the form` Tables: - `Then {user} sees table "{table_name}" with {n} rows` - `Then the table "{table_name}" should contain "{text}"` - `When {user} sorts table "{table_name}" by "{column}"` Auth: - `Given {user} is logged in as "{role}"` - `Given {user} is not authenticated` Assertions: - `Then {user} should see "{text}"` - `Then {user} should not see "{text}"` - `Then the element "{test_id}" should be visible` ### 3. Step Implementation Conventions - All steps use `data-testid` selectors for element targeting - Parameterize generically — avoid hardcoding entity names - Log actions at INFO level - Add module-level docstring listing all steps --- ## Agent proofs vs AT > Footnote — do not add PRF/TASK scenarios to the Gherkin Step Library. PRF-* integration proofs (lane 1) and TASK-* golden evals (lane 4) are pytest integration tests, not behave AT scenarios. They live under `tests/integration/agent/` and use `assert_agent_story` / structured oracles — not `docs/features/steps/`. \| Concern \| AT Step Library \| Agent proofs (PRF) \| Task eval (TASK) \| \|---------\|-----------------\|--------------------\|------------------\| \| Runner \| behave-django \| pytest `@agent_proof` \| pytest `@quality` \| \| Location \| `docs/features/steps/` \| `tests/integration/agent/` \| `tests/integration/agent/` or `tests/quality/` \| \| Assert \| Gherkin Then steps \| `assert_agent_story(trace, …)` \| Golden oracle YAML/JSON \| \| LLM \| None \| CAP-004 ScriptedLLM only \| Live provider (lane 4) \| \| Catalog \| Step Library Catalog \| SAO §17 PRF row map \| Fixture Library `agent_tasks/` \| When BPE or MIN declares `agent_proof_command` or `checkpoint.agent_proof_command`, implement pytest tests — do not invent Gherkin phrases for tool-call traces or blackboard state. Reuse AT steps only for human-facing GUI journeys; agent control-plane behavior belongs in lane 1/2 pytest per artifact 56 Part 4.5. TFK-07 may still add fixtures (`llm_scripts/`, `agent_tasks/`) when a PRF script or TASK golden is missing — that is fixture catalog work, not step library work.
#4	Build Fixture Library	Read the 'TFK-4 Build Fixture Library' activity from playbook 'Junior Edda' (workflow 'Test Automation Framework'). Follow its guidance when assisting me. # Build Fixture Library ## Objective Create a shared library of test fixtures at multiple scopes (session, suite, test) using both JSON fixtures and FactoryBoy. Establish patterns for context passing, AutoFixture support, and fixture presets. --- ## Process ### 1. Fixture Organization ``` tests/fixtures/ ├── seed.json # Base data loaded once per session ├── presets/ │ ├── team_preset.json # A group with set of users with specific roles │ ├── project_preset.json # Project with workflows, activities, artifacts │ └── empty_preset.json # Clean slate for isolation tests ├── factories/ │ ├── user_factory.py # FactoryBoy user factory │ ├── model_factories.py # Domain model factories │ └── __init__.py ├── autofixture/ │ └── fixture_creator.py # AutoFixture helper ├── llm_scripts/ # Lane 1 — ScriptedLLM queues (when SAO §17 applies) │ └── <prf-id>/ │ ├── happy.json │ └── reject_.json └── agent_tasks/ # Lane 4 — frozen TASK- corpora (when SAO §17 applies) └── <task-id>/ ├── input/ ├── expected.yaml └── meta.yaml ``` ### 2. When to Use JSON vs FactoryBoy \| Use JSON fixtures when... \| Use FactoryBoy when... \| \|---------------------------\|------------------------\| \| Data is static reference data \| Data needs to be parameterized per test \| \| Loaded once per session (seed data) \| Created dynamically with variations \| \| Represents "the world as it is" \| Represents "arrange" step of a specific test \| \| Shared across many tests unchanged \| Tests need unique data to avoid collisions \| ### 3. Fixture Scopes - Session-level (`seed.json`): loaded once via `loaddata` in `before_all` - Suite-level (`presets/`): loaded for a specific group of related tests - Test-level (FactoryBoy): created per test function, rolled back after ### 4. AutoFixture Support For lazy fixture creation — create model instances with sensible random defaults when you don't care about specific field values. --- ## Idempotent behave Given Steps (Background + scenario) When a feature file uses `Background:` to seed reference entities and scenarios add their own `Given` steps for the same natural keys (slug, code, username, composite unique): 1. Step definitions MUST use `get_or_create` or update-in-place — never blind `Model.objects.create()` for keys Background may already insert. 2. Document in the Step Library Catalog which Givens are idempotent vs create-only. 3. On `IntegrityError` during AT, first suspect double-seeding — fix the step, not the scenario order. Reference: Skill 45 Pattern 5 (Behave-Django BDD Runner). --- ## Fixture Library Catalog — agent eval entries When SAO §17 applies, extend the Fixture Library Catalog with two agent-specific roots. Skip catalog rows when §17 is N/A. ### `llm_scripts/<prf-id>/` (lane 1 — PRF integration proof) \| Catalog field \| Purpose \| Example \| \|---------------\|---------\|---------\| \| `prf_id` \| Artifact 56 row id \| `PRF-SC01-04` \| \| `path` \| Relative to `tests/fixtures/` \| `llm_scripts/PRF-SC01-04/happy.json` \| \| `variant` \| happy / reject_* \| `reject_429` \| \| `turn_count` \| Expected ScriptedLLM queue length \| `3` \| \| `linked_test` \| pytest module \| `tests/integration/agent/test_prf_sc01_04.py` \| \| `sao_ref` \| SAO §17 checkbox \| `PRF-SC01-04 dual-tool mode` \| File shape: ordered JSON array of LLM response strings or objects consumed by CAP-004 ScriptedLLM. Reject variants must exhaust the queue with an explicit error — never silent empty fallback (see TFK-08). ### `agent_tasks/<task-id>/` (lane 4 — TASK golden eval) \| Catalog field \| Purpose \| Example \| \|---------------\|---------\|---------\| \| `task_id` \| Artifact 56 Part 4.6 row \| `TASK-SC02-01` \| \| `path` \| Relative to `tests/fixtures/` \| `agent_tasks/TASK-SC02-01/` \| \| `sc_xx` \| Scenario family \| `SC-02` \| \| `fixture_ref` \| Frozen input corpus subpath \| `input/corpus.json` \| \| `oracle_type` \| Assert strategy \| `set_recall` / `graph_diff` / `schema_bounds` \| \| `pass_band` \| Promotion thresholds \| `min_recall: 0.95`, `max_extras: 1` \| \| `n_runs` \| Stability runs at temp=0 \| `3` \| \| `linked_test` \| pytest module \| `tests/integration/agent/test_task_sc02_01.py` \| Oracle schema (`expected.yaml` / `meta.yaml`): \| Field \| Required \| Description \| \|-------\|----------\|-------------\| \| `task_id` \| yes \| Matches catalog row \| \| `oracle_type` \| yes \| Drives assert helper selection \| \| `expected_names` \| set_recall \| Ground-truth name set \| \| `expected_graph` \| graph_diff \| Nodes/edges or ops diff spec \| \| `schema_bounds` \| schema_bounds \| JSON schema or field bounds \| \| `pass_band` \| yes \| min_recall, max_extras, max_latency_ms, etc. \| \| `n_runs` \| promotion \| Runs before certifying band \| \| `provider_pin` \| optional \| Model id for scoreboard (lane 3/4) \| Document dependencies (seed preset, factory hooks) in catalog notes. TFK-07 adds new rows when BPE/MIN introduces a PRF script or TASK golden not yet cataloged.
#5	Wire CICD Integration	Read the 'TFK-5 Wire CICD Integration' activity from playbook 'Junior Edda' (workflow 'Test Automation Framework'). Follow its guidance when assisting me. # Wire CICD Integration ## Objective Configure the CI/CD pipeline to run tests at appropriate stages: unit+integration+AT on CI (every push), E2E on staging (before release swap). Define pass/fail gates at each stage. --- ## Process ### 1. CI Pipeline Test Stages Modify `.github/workflows/ci.yml` (DCD-04 artifact) to add acceptance test stage: ```yaml jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install dependencies run: make provision - name: Lint run: make lint - name: Unit tests run: make test-unit - name: Integration tests run: make test-integration - name: Acceptance tests # NEW — TAF addition run: make test-at ``` Gate: All three test levels must pass before container build proceeds. ### 2. CD Pipeline E2E Stage Modify `.github/workflows/cd.yml` (DCD-05 artifact) to add E2E stage on staging: ```yaml e2e-staging: needs: deploy-idle runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install Playwright browsers run: playwright install chromium - name: Run E2E against staging run: make test-e2e BASE_URL=${{ vars.STAGING_URL }} DB_URI=${{ vars.STAGING_DB_URI }} - name: Upload screenshots if: always() uses: actions/upload-artifact@v4 with: name: e2e-screenshots path: tests/e2e/screenshots/ ``` Gate: E2E must pass on staging → create release → swap with prod. ### 3. Screenshot Archival - E2E tests capture a screenshot after every step - Screenshots uploaded as GitHub Actions artifacts for human review --- ## Agent eval CI (optional) When SAO §17 applies, add agent eval lanes without changing the default PR job shape in `ci.yml`. Agent-less projects: skip this section; Makefile targets no-op. ### Default `ci.yml` — UNCHANGED for agent-less and baseline PR flow The existing `test` job (unit → integration → AT) remains the merge gate for all projects. Do not add `-m live_llm`, `-m quality`, or unconditional `-m agent_proof` to the default PR workflow. Optional PR extension (agents only): append a conditional step when the repo enables agents: ```yaml - name: Agent control-plane proofs (lane 1) if: vars.AGENTS_ENABLED == 'true' env: AGENTS_ENABLED: true run: make test-agent-proof ``` Lane 2 (deterministic shell) already runs inside `make test-integration`. No separate job. ### Separate `.github/workflows/agent-eval.yml` Lanes 3–4 run outside the PR merge path: ```yaml name: Agent Eval on: workflow_dispatch: schedule: - cron: '0 6 * * ' # nightly lane 3 jobs: live-contract: if: vars.AGENT_EVAL_ENABLED == 'true' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: make provision - name: Lane 3 — live contract eval env: AGENTS_ENABLED: true LIVE_LLM_API_KEY: ${{ secrets.LIVE_LLM_API_KEY }} run: make test-agent-live task-quality: if: vars.AGENT_EVAL_ENABLED == 'true' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: make provision - name: Lane 4 — TASK golden quality env: AGENTS_ENABLED: true LIVE_LLM_API_KEY: ${{ secrets.LIVE_LLM_API_KEY }} run: make test-agent-quality ``` CD optional cert (lane 3):* in `cd.yml`, add staging agent contract step guarded by `if: vars.AGENT_EVAL_ENABLED == 'true'` — not required for promote when agents N/A. ### Gated Makefile targets (artifact 11) ```makefile test-agent-proof: ifeq ($(AGENTS_ENABLED),true) uv run pytest -m agent_proof tests/ else @echo "skip: agents N/A (SAO §17)" endif test-agent-live: ifeq ($(AGENTS_ENABLED),true) uv run pytest -m live_llm tests/ else @echo "skip: agents N/A (SAO §17)" endif test-agent-quality: ifeq ($(AGENTS_ENABLED),true) uv run pytest -m quality tests/ else @echo "skip: agents N/A (SAO §17)" endif ``` Gate summary: \| Target \| Lane \| PR (`ci.yml`) \| `agent-eval.yml` \| Promotion \| \|--------\|------\|---------------\|------------------\|-----------\| \| `test-agent-proof` \| 1 \| optional if `AGENTS_ENABLED` \| — \| — \| \| `test-integration` \| 2 \| always \| — \| — \| \| `test-agent-live` \| 3 \| never \| nightly / dispatch \| optional CD \| \| `test-agent-quality` \| 4 \| never \| manual / pre-promote \| pass band vs last cert \| Do not block merge on lane 3/4 flake. Empty `agent_proof` collection must not fail PR CI — enable the conditional step only after at least one PRF test lands.
#6	Establish E2E Infrastructure	Read the 'TFK-6 Establish E2E Infrastructure' activity from playbook 'Junior Edda' (workflow 'Test Automation Framework'). Follow its guidance when assisting me. # Establish E2E Infrastructure ## Objective Set up the end-to-end test infrastructure that enables "day in life" user journey testing via Playwright-driven browser automation. Location: `tests/e2e/` — standalone suite with its own `environment.py`, `steps/`, and `.feature` files. Not nested under AT. AT remains in `docs/features/` with Django test client steps. --- ## Sequencing contract (why order 6 after #189–#191 is correct) Chosen resolution (Galdr option c):* Activities #189–#191 cover AT concerns only. Activity #192 stands up independent E2E infrastructure. No resequence. \| Activity \| TFK label \| Scope \| Needs Playwright / `tests/e2e/` harness? \| \|----------\|-----------\|-------\|------------------------------------------\| \| #188 \| TFK-02 Bootstrap Test Harness \| Creates directory layout for both `docs/features/` (AT) and `tests/e2e/` (E2E placeholders), pytest, `behave.ini` \| No — only scaffolds paths \| \| #189 \| TFK-03 Build Step Library \| AT step implementations in `docs/features/steps/` + Step Library Catalog (phrases) \| No \| \| #190 \| TFK-04 Build Fixture Library \| Shared fixture data / presets used by AT (and later by E2E data load) \| No \| \| #191 \| TFK-05 Wire CICD Integration \| CI gates for unit/integration/`make test-at` \| No (E2E stays staging/release-only) \| \| #192 \| TFK-06 Establish E2E Infrastructure \| Playwright + LiveServer + `tests/e2e/environment.py` + journey features \| Yes — this activity \| \| #193 \| TFK-07 Add Step and/or Fixture \| Extends catalog; may add AT and/or E2E implementations \| As needed \| How #189–#191 exist without E2E infrastructure: AT runs via Django test client against `docs/features/` (`manage.py behave --simple`). That path never starts a browser. Fixtures and CI wiring for AT do not call Playwright. Therefore predecessors #189–#191 are valid without #192 being complete. What #188 already did vs what #192 does: #188 may create empty `tests/e2e/` directories and Makefile stubs. #192 makes that suite runnable (browser lifecycle, LiveServer, screenshots, `--base-url` / `--db-uri`). Empty dirs ≠ working E2E harness. Dual-path step maintenance: Catalog phrases are owned by #189 (TFK-03). AT Python lives in `docs/features/steps/`. E2E Playwright counterparts live in `tests/e2e/steps/` and are added when journeys need them (#192 seeds the harness; #193 adds missing phrase implementations). Not one merged module. Naming: Prefer Activity numeric IDs (#188–#195) in cross-references; TFK-0N labels are workflow abbreviations only. --- ## Clarifications (architecture contract) 1. Shared catalog, separate implementations. The Step Library Catalog (phrases/vocabulary) is shared between AT and E2E. Python step modules are not shared: AT in `docs/features/steps/` (Django test client); E2E in `tests/e2e/steps/` (Playwright). 2. "Same Gherkin phrases" means catalog alignment, not one code tree. Missing phrases → Activity #193 (TFK-07). 3. No activity reorder. Placement after #191 is intentional: AT stack first, E2E harness second. #192 does not unblock #189–#191. --- ## Key Concepts ### E2E vs Acceptance Tests \| Aspect \| Acceptance Test (AT) \| E2E Test \| \|--------\|---------------------\|----------\| \| Focus \| Proving ONE feature works \| Fulfilling a GOAL using system means \| \| Path \| `docs/features/` \| `tests/e2e/` \| \| Engine \| Django test client (`behave --simple`) \| Playwright + LiveServer \| \| Scope \| Single .feature, single scenario \| Multi-phase .feature, sequential \| \| Speed \| Fast (no browser) \| Slow (real browser, screenshots) \| \| When \| Every CI run \| Staging before release \| ### Big Idea: Certify Any Environment Using `--base-url=...` we can point Playwright at any place where the application runs: - `--base-url=http://localhost:8000` — local development - `--base-url=https://staging.example.com` — staging - `--base-url=https://app.example.com` — production smoke test Similarly `--db-uri=...` points where initial setup has to be loaded. --- ## Process ### 1. E2E Configuration ```bash make test-e2e BASE_URL=https://staging.example.com DB_URI=postgres://... # → manage.py behave tests/e2e/ ``` ### 2. E2E Feature Structure Each E2E test is written as one long multi-phase `.feature` file under `tests/e2e/` running sequentially. ### 3. Screenshot on Every Step `tests/e2e/environment.py` captures a screenshot after every step for visual verification and debugging. --- ## E2E Session Authentication (mandatory) When E2E steps require a logged-in browser session on a Django app: 1. Seed or factory-create the user in the test database. 2. Use Django test `Client().force_login(user)` — read the `sessionid` cookie. 3. Inject the cookie into Playwright via `page.context.add_cookies([...])` before navigating to protected routes. 4. Provide a shared helper in `tests/e2e/steps/` (e.g. `force_login_playwright`) — do not duplicate per feature. Anti-patterns: manual `SessionStore`; assuming UI login flow exists before AUTH screens ship; AT-only auth patterns copied without cookie injection. Reference: Skill 45 Pattern 4 (Behave-Django BDD Runner). Seed this helper when bootstrapping the E2E harness in this activity.