Activities

Name	Abbrev.	Workflow	Playbook	Phase	Actions
Scope Sources, Org, and Environment	MCE-1	Model and Deploy Infrastructure as Code	Delivery Constraint & Opportunity Analysis	Datalake Formation (#1)	Read the 'MCE-1 Scope Sources, Org, and Environment' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Model and Deploy Infrastructure as Code'). Follow its guidance when assisting me. ## Purpose Write the Lake Scope Contract before any AWS resource is modeled. Later activities read only this file for org, sources, CI host, AWS account, region, buckets, Athena view names, lake repo, OIDC sub, and secret keys. ## Inputs - Artifact Operations Lake Starter Kit — clone `https://github.com/FeatureFactory-io/ops-lake-starter` (Use this template). Not the live opsdl lake. - Human target (GitHub org / GitLab group / Jira site). - `aws sts get-caller-identity` and configured region. - Where the lake repo will live (GitHub vs GitLab). - Skill Scope the Operations Lake → Copy-this YAML (and Jira flow keys if jira is scoped). ## Steps 1. Clone the starter kit into the org (GitHub → Use this template). Rename `lake_repo` if the clone is not `ops-lake-starter`. Open skill Scope the Operations Lake. 2. Fill `docs/lake-scope-contract.yaml` in the clone: `org`, `host`, `sources`. List repos: `gh api orgs/{org}/repos --paginate`. Projects v2: `gh api graphql -f query='query($org:String!){organization(login:$org){projectsV2(first:20){nodes{id title}}}}' -f org=YOUR_ORG`. Default github entities = commits, pull_requests, issues, workflow_runs, project_items. Drop unused. Do not add gitlab or jira unless this org uses them. 3. Set `ci` to exactly one of `github_actions` \| `gitlab_ci` matching `host`. 4. Fill `aws_account`, `aws_region`, `env`, `lake_name`, `lake_repo`, `oidc_sub`. Derive `views` as `{source}_{entity}` (copy-this list is in the YAML). 5. Fill `secrets.github_webhook` and `secrets.github_api_token`. GitHub Actions PAT secret must not be named `GITHUB_` — use `OPSLAKE_GITHUB_PAT`. If `jira` is in `sources`, copy skill 106 Jira flow keys* (project keys, started_statuses, jira views) — otherwise ignore skill Jira Flow Extract. 6. Canonical paths in the template (raw JSON vs curated Hive Parquet). Two buckets, always. Keep `streamlit/data/contract_views.yaml` in sync with `views` so mart tabs skip correctly. ## Done when - Starter kit cloned (not opsdl). - `docs/lake-scope-contract.yaml` is filled and committed. - `views` is the complete catalog surface later activities will create. - `ci` is XOR; `lake_repo` and `oidc_sub` are set. ## Feeds Activity Model the Data Lake as CDK Stacks.
Model the Data Lake as CDK Stacks	MCE-2	Model and Deploy Infrastructure as Code	Delivery Constraint & Opportunity Analysis	Datalake Formation (#1)	Read the 'MCE-2 Model the Data Lake as CDK Stacks' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Model and Deploy Infrastructure as Code'). Follow its guidance when assisting me. ## Purpose Model every AWS resource the lake needs as a Python CDK app (TypeScript only if the host repo is already TypeScript). No console clicks. No separate SAM template. ## Inputs - Starter clone `infra/` already has four stacks. Customize from the filled contract; do not scaffold empty. - `docs/lake-scope-contract.yaml`. Instantiate only sources/tables listed there. - Skill AWS CDK Infrastructure as Code → Recipe / Copy-this tests. ## Steps 1. Open skill AWS CDK Infrastructure as Code. Files to touch: `infra/ops_lake/scope.py` (loader), then `deploy_stack.py`, `ingestion_stack.py`, `catalog_stack.py`, `eda_stack.py` only as the contract requires. Do not scaffold empty `infra/`. 2. `DeployStack`: GitHub (or GitLab) OIDC + deploy IAM role. Trust both name-only and ID-qualified `sub` patterns (skill GitHub Actions CI/CD → Copy-this IAM trust). Output `DeployRoleArn` for `AWS_DEPLOY_ROLE_ARN`. 3. `IngestionStack`: raw + curated + athena-results buckets (names from contract), `BucketEncryption.KMS_MANAGED` and `bucket_key_enabled=True`, lifecycle; HTTP API; one webhook Lambda per scoped source; `GithubBackfillFn` (10 min / 1024 MB); EventBridge poller for Projects v2 if github scoped (heartbeat until GraphQL ships); DynamoDB cursor; SQS; `ParquetTransformFn`. Do not attach a customer-managed `kms.Key` to buckets that notify SQS. If jira scoped, wire `jira_flow.py` copied from `infra/lambdas/jira_flow.py.example`. 4. `CatalogStack`: Glue database `athena_database`; one crawler per contract `views` on `s3://{curated}/{table}/`; Athena workgroup; named preview queries matching `views`. 5. `EdaStack`: Streamlit on ECS Fargate + ALB (`linux/amd64`). Dockerfile COPY `.py`, `pages/`, and `data/`. Grant task role Athena, Glue GetTables, curated-bucket read, Athena-results read/write. Output `StreamlitMartUrl`. 6. Environment from CDK context / SSM. Synth: from repo root `cdk synth -c skip_bundling=true` (or `cd infra` if that is how this clone is wired). 7. Pytest: `tests/unit/test_deploy_stack.py`, `test_ingestion_stack.py`, `test_catalog_stack.py`, `test_eda_stack.py`, `test_story_data.py`. Assert BucketKeyEnabled on all three lake buckets. ## Done when - `infra/app.py` instantiates all four stacks. - Synth tests pass, including S3 Bucket Keys. - GitHub-only contract → no GitlabWebhookFn / live JiraPollFn. ## Feeds XOR: Deploy via GitHub Actions* or Deploy via GitLab CI.
Deploy via GitHub Actions	MCE-3	Model and Deploy Infrastructure as Code	Delivery Constraint & Opportunity Analysis	Datalake Formation (#1)	Read the 'MCE-3 Deploy via GitHub Actions' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Model and Deploy Infrastructure as Code'). Follow its guidance when assisting me. ## Purpose Deploy the CDK app through GitHub Actions with OIDC. Production path for a GitHub-hosted lake repo. ## Inputs - Lake Scope Contract (`ci` must be `github_actions`). - CDK Application (includes DeployStack). - Starter `.github/workflows/deploy.yml` — copy from the clone; do not invent a second pipeline. Template: `https://github.com/FeatureFactory-io/ops-lake-starter/blob/main/.github/workflows/deploy.yml`. - Skill GitHub Actions CI/CD → Recipe. ## Skip when `ci` is `gitlab_ci`. Do not create deploy.yml "just in case". ## Steps 1. Keep starter `.github/workflows/deploy.yml`. 2. Chicken-and-egg: laptop, same region as the contract: `cdk bootstrap` then `cdk deploy OpsLakeDeploy` (or `--all`) once. Read `DeployRoleArn` from stack outputs. GitHub → Settings → Secrets and variables → Actions → New repository secret `AWS_DEPLOY_ROLE_ARN`. Also `OPSLAKE_GITHUB_PAT` (`repo`, `read:org`). Never `GITHUB_`. After that, never `cdk deploy` a shared env from a laptop. 3. `permissions: id-token: write`. Assume the deploy role via `aws-actions/configure-aws-credentials`. No `AWS_ACCESS_KEY_ID`. 4. Jobs: pytest → `cdk deploy --all --require-approval never`. Print `DeployRoleArn`, `GithubWebhookUrl`, `StreamlitMartUrl` to the job summary. IAM simulate Streamlit task-role S3 read. 5. OIDC trust both* `repo:{org}/{lake_repo}:` and `repo:{org}@/{lake_repo}@:`. A `main` push AssumeRoleWithWebIdentity must succeed (check the Actions log). 6. After first GHA deploy, record URLs/ARNs in `docs/deploy-manifest.yaml`. Org webhook registration is the next human step (activity Stand Up Serverless Ingestion) — deploy does not by itself land events. ## Done when - Workflow file is the only shared-env deploy path. - OIDC covers both `sub` shapes; `AWS_DEPLOY_ROLE_ARN` is set. ## Feeds Pipeline + populate-lake. Shared-env resources appear only after this workflow runs on `main`.
Deploy via GitLab CI	MCE-3	Model and Deploy Infrastructure as Code	Delivery Constraint & Opportunity Analysis	Datalake Formation (#1)	Read the 'MCE-3 Deploy via GitLab CI' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Model and Deploy Infrastructure as Code'). Follow its guidance when assisting me. ## Purpose Deploy the CDK app through GitLab CI with OIDC. Alternative to GitHub Actions. ## Inputs - Lake Scope Contract (`ci` must be `gitlab_ci`). - CDK Application. - Starter `.gitlab-ci.yml.example` — copy to `.gitlab-ci.yml`. Skill GitLab CI/CD → Recipe. ## Skip when `ci` is `github_actions`. Running both against one AWS account causes split-brain deploys. ## Steps 1. Copy `.gitlab-ci.yml.example` to `.gitlab-ci.yml`. Do not also keep a live GitHub `deploy.yml` against this account. 2. Chicken-and-egg: laptop `cdk bootstrap` then one `cdk deploy OpsLakeDeploy` to mint the GitLab OIDC IAM role. Store the role ARN as CI/CD variable `AWS_DEPLOY_ROLE_ARN` (not `AWS_ACCESS_KEY_ID`). Trust `aud` = `https://gitlab.com` (or this instance URL) and the project `sub`. 3. `id_tokens` block mints the OIDC token. pytest → `cdk synth` → `cdk diff` → `cdk deploy` with `when: manual` for production. Register GitLab Environment `production`. 4. After first deploy, record URLs/ARNs in `docs/deploy-manifest.yaml`. ## Done when - `.gitlab-ci.yml` is the only shared-env deploy path. - GitHub Actions deploy workflow is absent. - A `main` pipeline assumed the role. ## Feeds Pipeline (populate equivalent on GitLab if you add it; otherwise GitHub populate-lake is the GitHub-ci path).
Stand Up Serverless Ingestion from Scoped Sources	BPE-1	Build the Operational Data Lake Pipeline	Delivery Constraint & Opportunity Analysis	Datalake Formation (#1)	Read the 'BPE-1 Stand Up Serverless Ingestion from Scoped Sources' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Build the Operational Data Lake Pipeline'). Follow its guidance when assisting me. ## Purpose Land raw JSON events from scoped sources into the raw bucket. Implement only Lambdas the Scope Contract lists. Org webhook registration is a human GitHub (or GitLab) Settings step after the first CI deploy — deploy does not by itself land events. ## Inputs - Lake Scope Contract (`sources`, `views`, bucket names, `secrets.github_webhook`). - CDK Application (IngestionStack already declares the functions). Gate is the artifact — predecessors cannot cross workflows. - Stack output `GithubWebhookUrl` (job summary after `deploy.yml`, also `docs/deploy-manifest.yaml`). - Skill Serverless Data Ingestion → Recipe. ## Steps 1. Open skill Serverless Data Ingestion. Handlers already live under `infra/lambdas/` in the starter (`github_webhook.py`, and `jira_flow.py` only after you copy `infra/lambdas/jira_flow.py.example`). Edit signatures / secret names from the contract; do not scaffold empty. 2. Confirm Secrets Manager `ops-lake/github-webhook-secret` exists (CDK creates it; populate-lake may sync). Value must match the GitHub webhook secret you will paste in org Settings. 3. Register the org webhook (human): GitHub org → Settings → Webhooks → Add webhook. Payload URL = `GithubWebhookUrl`. Content type `application/json`. Secret = the Secrets Manager value. SSL verify. Events: Issues, Pull requests, Pushes, Workflow runs. Save. Send a test ping. 4. GitHub handler: `GithubWebhookFn` behind `/webhooks/github`, verify `X-Hub-Signature-256`. Return 200; enqueue SQS for slow work. Prove: CloudWatch `/aws/lambda/GithubWebhookFn`; raw object at `s3://{raw}/github/{yyyy}/{mm}/{dd}/`. 5. GitLab: implement only if `gitlab` is in the contract. Secret `ops-lake/gitlab-webhook-secret`; header `X-Gitlab-Token` (skill 63). 6. Jira: implement only if `jira` is in the contract. Copy `infra/lambdas/jira_flow.py.example` → `jira_flow.py`. The poller lands raw JSON. Historical issues, changelog, and lead/cycle clocks are Backfill Historical Jira Issues and Status History plus skill Jira Flow Extract — a current-status poller is not a cycle-time extract. 7. Write unmodified JSON to `s3://{raw}/{source}/{yyyy}/{mm}/{dd}/{event-id}.json`. No Parquet here. 8. Idempotent on event id. `GithubProjectsPollFn` remains a heartbeat until GraphQL pagination ships — do not join `github_project_items` as a populated Master Roadmap. ## Done when - Org webhook is registered (or GitLab equivalent if that host is scoped). - One working handler per scoped source; zero handlers for unscoped systems. - Test ping produced a raw object (or CloudWatch shows a verified 200). - Secrets live in Secrets Manager / SSM, referenced from CDK. ## Feeds Backfill Historical GitHub Events (when github is scoped), Backfill Historical Jira Issues and Status History (when jira is scoped), then Store Compressed and Partitioned in S3.
Backfill Historical GitHub Events	BPE-2	Build the Operational Data Lake Pipeline	Delivery Constraint & Opportunity Analysis	Datalake Formation (#1)	Read the 'BPE-2 Backfill Historical GitHub Events' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Build the Operational Data Lake Pipeline'). Follow its guidance when assisting me. ## Purpose Pull historical GitHub issues, PRs, commits, and workflow runs into the raw bucket so Constraint and Flow Analysis can compute cycle time. Webhooks only catch events after they are registered. ## Inputs - Lake Scope Contract (`repos`, `secrets.github_api_token`). - CDK Application (`GithubBackfillFn` already declared). - Starter workflow `.github/workflows/populate-lake.yml` — template `https://github.com/FeatureFactory-io/ops-lake-starter/blob/main/.github/workflows/populate-lake.yml`. Do not laptop-invoke against shared env. - Skills Serverless Data Ingestion and Populate the Lake. ## Steps 1. Keep starter `infra/lambdas/github_backfill.py` and `populate-lake.yml`. Open skill Populate the Lake. 2. Issues and pulls: `state=all` and `per_page=100`. GitHub's default is open only — that was the empty cycle-time dashboard. Wrap each item `{backfill: true, kind, repo, payload}` with `kind` in `issues` \| `pulls` \| `commits` \| `workflow_runs`. 3. Paginate `Link: rel=next` for list endpoints. Commits API pagination is not the same as issue/PR Link headers — follow `page=` until empty. Timeout 10 minutes / 1024 MB. 4. Repo secret `OPSLAKE_GITHUB_PAT` (`repo`, `read:org`) — never `GITHUB_`. Populate-lake syncs it into Secrets Manager. 5. GitHub → Actions → Populate the Lake* → Run workflow. Watch CloudWatch for `written=N`. Never laptop invoke against shared env. 6. After raw objects land, the same workflow runs `scripts/sync_raw_to_curated.py` then crawlers then Athena proof. Athena LIMIT 10 is activity Present the Catalog via Athena; here you only need `written=N` and raw keys under `s3://{raw}/github/`. ## Done when - Glue `github_issues` will contain closed rows after Parquet + crawl (`payload.state='closed'`), not only open. - CloudWatch shows `written=N` for issues, pulls, commits, workflow_runs. ## Feeds Store Compressed and Partitioned in S3, then Glue/Athena. Cycle-time EDA depends on this history. ## Honesty `GithubProjectsPollFn` is a heartbeat until GraphQL pagination ships. Do not join `github_project_items` as if Master Roadmap items are populated.
Store Compressed and Partitioned in S3	BPE-3	Build the Operational Data Lake Pipeline	Delivery Constraint & Opportunity Analysis	Datalake Formation (#1)	Read the 'BPE-3 Store Compressed and Partitioned in S3' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Build the Operational Data Lake Pipeline'). Follow its guidance when assisting me. ## Purpose Turn raw landing-zone JSON into Hive-partitioned Parquet in the curated bucket. ## Inputs - Raw Operational Events (S3 Landing Zone). - CDK Application (`ParquetTransformFn` lives in IngestionStack). - Lake Scope Contract paths: raw vs curated. - Populate-Lake Pipeline (batch transform after backfill). - Skill S3 Data Partitioning and Compression → Recipe step 2 (event→table map). ## Canonical layout (do not invent another) - Raw: `s3://{raw}/{source}/{yyyy}/{mm}/{dd}/{event-id}.json` - Curated: `s3://{curated}/{table}/source={source}/dt={yyyy-mm-dd}/part-{uuid}.parquet` - `{table}` is a name from contract `views`. Two buckets, always. ## Steps 1. Open skill S3 Data Partitioning and Compression. Handler path: `infra/lambdas/parquet_transform.py` (`_normalize_row` omits `source`). 2. Event → table map (skill 64 recipe 2): `push` → `github_commits`, `pull_request` → `github_pull_requests`, `issues` → `github_issues`, `workflow_run` → `github_workflow_runs`; backfill `kind` `commits`/`pulls`/`issues`/`workflow_runs`. Projects v2 → `github_project_items` only when that poller is real. 3. `ParquetTransformFn` writes pyarrow Parquet. Omit `source`/`dt` from the row body — they are Hive partitions only. 4. Webhooks: SQS buffer. Backfill: `scripts/sync_raw_to_curated.py` from populate-lake only, not a laptop against shared env. 5. Lifecycle: hot recent partitions Standard; cold raw/history IA or Glacier. 6. Confirm lake buckets have S3 Bucket Keys (`bucket_key_enabled=True`) via pytest synth (`tests/unit/test_ingestion_stack.py`), not the S3 console encryption tab alone. 7. If `jira` is scoped, run Backfill Historical Jira Issues and Status History (sibling of GitHub backfill) before Glue — this activity's predecessor is GitHub backfill only because workflows cannot cross-link both. ## Done when - Curated prefixes exist for every contract `views` entry that backfill produced. - Glue can crawl without "duplicate columns". - No EMR/Spark cluster. - SSE-KMS Bucket Keys are on (new objects do not call KMS per Put/Get). ## Feeds Catalog with AWS Glue.
Backfill Historical Jira Issues and Status History	BPE-3	Build the Operational Data Lake Pipeline	Delivery Constraint & Opportunity Analysis	Datalake Formation (#1)	Read the 'BPE-3 Backfill Historical Jira Issues and Status History' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Build the Operational Data Lake Pipeline'). Follow its guidance when assisting me. ## Purpose When `jira` is in the Scope Contract, pull historical issues plus a status timeline into the raw bucket so Constraint and Flow Analysis can compute lead time and cycle time. A poller that only sees current status cannot reconstruct cycle start. ## Skip when Scope Contract `sources` does not include `jira`. Do not stand up Jira Lambdas or views "just in case". Do not copy `jira_flow.py.example` onto a GitHub-only lake. ## Inputs - Lake Scope Contract (`sources`, project keys from skill Scope the Operations Lake → Jira flow keys, `views`, Started status set, watermark / secret names). - Starter stub `infra/lambdas/jira_flow.py.example` — copy to `infra/lambdas/jira_flow.py` only if jira is scoped. - CDK Application (`JiraPollFn` / Jira backfill function already declared when jira is scoped). - Skill Jira Flow Extract → Extraction recipe. - Skill Serverless Data Ingestion (handler wiring only). ## Steps 1. If jira is scoped: copy `infra/lambdas/jira_flow.py.example` → `jira_flow.py`. Open skill Jira Flow Extract → Extraction recipe. Implement that contract — do not invent a different clock. Secret `ops-lake/jira-api-token`; base URL from contract Jira flow keys. 2. Persist both issue snapshots (`closed_at` = `resolutiondate`) and status segments (`status`, `entered_at`, `exited_at`). 3. JQL is scoped and bounded (`updatedDate`). Cloud: cursor pagination. Server/DC: `startAt`. Page size about 100. 4. Build the timeline from changelog `field == status`. Paginate per-issue changelog when search expand truncates. 5. Record the Started status set on the contract. Compute lead and cycle from the landed columns (business days). Do not re-query Jira in EDA for those clocks. 6. Incremental cursor in DynamoDB keyed by `source`. Periodic bounded backfill for tickets older than the watermark. Populate-lake today is GitHub-shaped — if you add a Jira invoke job, put it in the same workflow; do not laptop-invoke shared env. 7. Write unmodified JSON to `s3://{raw}/jira/{yyyy}/{mm}/{dd}/{event-id}.json`. Parquet is the next activity. ## Done when - Glue (or the contract views) contain resolved rows (`closed_at` not null), not only open issues. - `jira_status_segments` (or the named contract view) has at least one closed segment per resolved issue that has changelog. - Athena proof LIMIT 10 succeeds for every jira view that has Parquet. - Lead/cycle can be computed from curated columns without another Jira call. ## Feeds Store Compressed and Partitioned in S3, then Glue/Athena. Constraint analysis may use these clocks as measured touch/wait inputs; it does not replace impact scoring. ## Honesty Sprint/velocity board reports are out of scope here. Do not treat them as lead or cycle.
Catalog with AWS Glue	BPE-4	Build the Operational Data Lake Pipeline	Delivery Constraint & Opportunity Analysis	Datalake Formation (#1)	Read the 'BPE-4 Catalog with AWS Glue' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Build the Operational Data Lake Pipeline'). Follow its guidance when assisting me. ## Purpose Register curated prefixes in Glue so Athena can see tables without hand-written DDL. ## Inputs - Partitioned Parquet Data Lake. - Lake Scope Contract (`athena_database` default `ops_catalog`, `views`). - Populate-Lake Pipeline (one-shot crawler start). Starter: `.github/workflows/populate-lake.yml`. - Skills AWS Glue Cataloging and Populate the Lake. ## Steps 1. Open skills AWS Glue Cataloging and Populate the Lake. Do not start crawlers in the Glue console. 2. One database named from contract `athena_database` (default `ops_catalog`). One crawler per `views` entry, scoped to `s3://{curated}/{table}/`. CDK already declared them — intern does not click Create crawler. 3. Daily schedule `cron(0 6 * * ? )` plus populate-lake job step `start-crawler` after Parquet sync. Wait until State=READY: `aws glue get-crawler --name {table}_crawler` (name from CatalogStack). 4. Built-in Parquet classifier only unless a source fails auto-detect. 5. If Glue reports duplicate columns, go back to Store Compressed and Partitioned in S3* (`source` leaked into Parquet body). Do not patch the crawler. 6. Escalate to Operations Analyst before applying a crawler change that alters an existing column type. ## Done when - Glue tables exist for every contract view that has Parquet (table name = view name). - No crawlers for unscoped systems. ## Feeds Present the Catalog via Athena.
Present the Catalog via Athena	BPE-5	Build the Operational Data Lake Pipeline	Delivery Constraint & Opportunity Analysis	Datalake Formation (#1)	Read the 'BPE-5 Present the Catalog via Athena' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Build the Operational Data Lake Pipeline'). Follow its guidance when assisting me. ## Purpose Prove the Athena surface. Glue crawler tables are the contract views. Downstream consumers (Streamlit, Pandas, MCP) query those tables (or thin views if you add them), never random Glue names. ## Inputs - AWS Glue Data Catalog. - Lake Scope Contract (`views`, `athena_workgroup` default `ops-lake-analysts`, `athena_database` default `ops_catalog`). - Populate-Lake Pipeline. - Skills Athena SQL Querying and Populate the Lake. - SQL template `sql/proof_views.sql` (placeholders `{database}`, `{view}`). ## Steps 1. Open skills Athena SQL Querying and Populate the Lake. 2. One workgroup from contract `athena_workgroup` (AWS name default `ops-lake-analysts`) with `EnforceWorkGroupConfiguration` and a per-query scan cap (start 5GB). 3. After crawlers READY, populate-lake runs `scripts/create_athena_views.py` — LIMIT 10 per contract view; skip missing tables. Do not laptop-run against shared env. Console alternative: Athena query editor → workgroup dropdown `ops-lake-analysts` → database `ops_catalog`. 4. Copy-this proof: `SELECT COUNT() AS n FROM {view} WHERE source = '{source}'` then `SELECT FROM {view} LIMIT 10`. Backfill JSON: extract `$.payload.`. Prefer closed snapshots when deduping issue numbers. Record each `QueryExecutionId` on artifact Athena Catalog Views. 5. Glue tables already are* the views; the script is a proof runner, not a second catalog of DDL. 6. Hands off to Operations Analyst when all contract views that have data are queryable. ## Done when - Each populated contract view runs a `SELECT ... LIMIT 10` in the workgroup. - Streamlit/Pandas/MCP are pointed at these tables/views only. ## Feeds Constraint and Flow Analysis (artifact gate).
Map the BizDevTestSecOps Value Stream	CAS-1	Constraint and Flow Analysis	Delivery Constraint & Opportunity Analysis	Exploratory Data Analysis (#2)	Read the 'CAS-1 Map the BizDevTestSecOps Value Stream' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Constraint and Flow Analysis'). Follow its guidance when assisting me. ## Purpose Draw the BizDevTestSecOps map from catalog events that exist, not from a generic GitLab/Jira cartoon. ## Inputs - Queryable catalog views (pipeline done, including closed-issue backfill). - Lake Scope Contract: `docs/lake-scope-contract.yaml` key `views`. - Starter file `streamlit/data/value_stream.yaml` (human notes: `docs/analysis/value-stream-map.md`). - Skill Value Stream and Constraint Analysis → Recipe steps 2 and 4. - Skill Athena SQL Querying → Recipe (workgroup, LIMIT 10, `$.payload.`). ## Steps 1. Open `docs/lake-scope-contract.yaml` → `views`. Those names are* the Glue/Athena tables. 2. Prove each view is queryable: run `scripts/create_athena_views.py` (populate-lake, not a laptop against shared env) or `sql/proof_views.sql` in workgroup `athena_workgroup` (default `ops-lake-analysts`). `SELECT COUNT()` then `LIMIT 10`. Paste `QueryExecutionId` onto the matching row in `streamlit/data/value_stream.yaml`. If n=0 or the table is missing, stop — do not invent a stage. 3. Open `streamlit/data/value_stream.yaml`. Default five stages (skill Value Stream → Recipe step 2): - Biz* — `github_issues` opened (`$.payload.created_at`); join issue number - Dev — `github_pull_requests` opened → merged; `github_commits` in window; join `Closes #N` - Test — `github_workflow_runs` start → first `conclusion=success` - Sec — security-gate job in that run, or a dedicated scan workflow - Ops — deploy workflow run start → complete Delete any row whose `view` is not in `views`. Uncomment gitlab/jira only if those sources exist. Do not use heartbeat `github_project_items` as Biz. 4. Feature-type cohort: skill Value Stream → Recipe step 4 (classifier). Do not map every issue. 5. Commit the filled YAML. That is artifact BizDevTestSecOps Value Stream Map. ## Done when - Map names real view+column pairs for each stage boundary. - Every remaining row has a QueryExecutionId (or an explicit empty-table stop). - No stage points at a table that is not in `views`. ## Feeds Score Cycle Impact.
Score Cycle Impact	CAS-2	Constraint and Flow Analysis	Delivery Constraint & Opportunity Analysis	Exploratory Data Analysis (#2)	Read the 'CAS-2 Score Cycle Impact' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Constraint and Flow Analysis'). Follow its guidance when assisting me. ## Purpose Reconstruct touch vs wait, score impact, and mark where AI could help. Do not design agents. ## Formula - wall-clock = touch_time + wait_time - effort = people_in_role × touch_time - impact = effort + (people_downstream × wait_time) ## Inputs - Filled `streamlit/data/value_stream.yaml`. - `sql/stage_touch_wait.sql` and skill Cycle Impact Scoring → Recipe. - Skill AI Leverage Mapping → Recipe. - Role capacity file `streamlit/data/role_capacity.yaml`. ## Steps 1. Open `streamlit/data/cost_of_delay.yaml`. For each stage on the map, set `touch_time` and `wait_time` from catalog events (issue → PR → CI → merge → deploy). Never treat wall-clock as effort. Label measured vs assumed. Pin `query_execution_id` from `sql/stage_touch_wait.sql` (workgroup from the contract; extract `$.payload.`). 2. Fill `streamlit/data/role_capacity.yaml`: people_in_role, people_downstream, source of the assumption. Do not* infer headcount from unique GitHub authors. 3. Join issue↔PR on `Closes #N` in payload, never `repo` or timestamps alone. 4. Compute effort, wall-clock, impact (worked sample in the YAML: Sec wait 48h × 8 downstream + 2h touch × 1 person = 386). Keep ToC #1 visible (`toc_rank_1: true`). 5. Fill `streamlit/data/ai_opportunities.yaml`: opportunity names, `ai_can_help` yes/no/unknown, effort S–XL. Low hanging fruit = high impact AND AI-yes AND low effort. No agent products. 6. Those three YAML files are artifacts Delivery Cycle Reconstruction, Cost of Delay Ranking, and AI Opportunity Prioritization Matrix. ## Done when - Ranking has impact scores with measured/assumed labels and one named #1 constraint. - Matrix has at least the high-impact boxes scored; no agent names. ## Feeds Look until trusted, then Triage: Eliminate / Automate / Delegate. ## Skip Do not optimize a non-constraint. Do not put AI on a low-impact stage because it is easy.
Look until Trusted	CAS-3	Constraint and Flow Analysis	Delivery Constraint & Opportunity Analysis	Exploratory Data Analysis (#2)	Read the 'CAS-3 Look until Trusted' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Constraint and Flow Analysis'). Follow its guidance when assisting me. ## Purpose See the delivery cycle as people live it until the impact ranking can be trusted. This is not a query-console step. ## Inputs - `streamlit/data/cost_of_delay.yaml`, `ai_opportunities.yaml`, `role_capacity.yaml`. - Mart URL: `docs/deploy-manifest.yaml` → `streamlit_mart_url`. - Notebook `notebooks/look-until-trusted.ipynb`. - Skills EDA with Streamlit Data Mart, EDA with Pandas and Jupyter, MCP-Driven Conversational Analytics, Metric Render Catalog → Render pairings / Starter mart tabs. ## Steps 1. Open the mart URL. Home is Delivery cycle, then Opportunity quadrant. Feature Cycle Time (`pages/11_Feature_Cycle_Time.py`) is a check, not the ranking. 2. Look at the whole flow first. Use Metric Render Catalog pairings to challenge the #1 constraint (lead/cycle, throughput, MR hours, CI failure, load). Skip any family whose contract views are missing. 3. Challenge assumed numbers in `role_capacity.yaml`; relabel or remeasure. Jira `status_segments`: touch/wait may be measured (business days). Do not mix with PR hours. 4. Chat/MCP findings are hypotheses until reproduced in `notebooks/look-until-trusted.ipynb` (Restart & Run All). 5. Copy survivors into `streamlit/data/promoted_eda.yaml` (metric id, pairing, unit, n, window, agrees_with_ranking, query_execution_id, tsy_section). Empty file (`rows: []`) is valid if nothing earned TSY — that is not a Present Findings bug. ## Pitfalls - If `LoginRefreshRequired` / `CreateOAuth2Token` expired → `aws login`, restart kernel, not a Glue/Athena ACL bug. Skill Athena SQL Querying / EDA with Pandas and Jupyter. ## Done when - Impact ranking survives a second look (or was corrected in YAML). - Any finding that will inform triage has query text + QueryExecutionId. - Catalog checks that disagree with the ranking are explained or the ranking is updated. ## Feeds Triage: Eliminate / Automate / Delegate.
Triage: Eliminate / Automate / Delegate	CAS-4	Constraint and Flow Analysis	Delivery Constraint & Opportunity Analysis	Exploratory Data Analysis (#2)	Read the 'CAS-4 Triage: Eliminate / Automate / Delegate' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Constraint and Flow Analysis'). Follow its guidance when assisting me. ## Purpose Decide eliminate vs automate vs delegate for ranked impact constraints, in that order, in writing. Tag cause layers (dE / dK / dI) and route each tag. ## Inputs - `streamlit/data/cost_of_delay.yaml` and `ai_opportunities.yaml`. - Skill Eliminate/Automate/Delegate Triage → Cause tags / Routes. - Template `streamlit/data/action_register.yaml`. ## Steps 1. Open `streamlit/data/action_register.yaml`. One row per ranked constraint, impact order. Fill eliminate first; automate only if eliminate is written no; delegate only if automate cannot encode the judgment. 2. The AI matrix may inform where automate or delegate could apply. It does not skip eliminate and it is not an agent backlog. 3. Automate shape: one Lambda + one Guardrail (policy / allow-list / human approval — name the check, not a product). 4. Tag cause layers on each row (multi-tag allowed). Skill → Cause tags: - dE environment (tool, process, incentive, data, time, authority) - dK knowledge/skill (trainable / selectable) - dI individual (selection, capacity, motivation) "Knows the right move, environment punishes it" stays dE, not dK. 5. Route per tag (skill → Routes): dE+eliminate → drop; dE+process/tooling → process/tooling (not AI SDLC); dE+automate/delegate → AI SDLC candidate; dK → Team Upskill Engine input (stage, clock, unit, n, role); dI → staffing. Do not author TUE modules. 6. Escalate #1 if neither eliminate nor automate works — flow redesign. Do not implement the Lambda in this activity. ## Done when - `action_register.yaml` has decision, cause tags, route, and evidence (clock, unit, n, role) for #1 and every ranked row you touched. - No dK row claims a finished curriculum. No dE process/tooling row is labeled AI SDLC unless automate or delegate was chosen. ## Feeds Tell the Data Story (publish this register — do not re-classify).
Design the Big-Picture-to-Detail Narrative	TSY-1	Tell the Data Story	Delivery Constraint & Opportunity Analysis	Presenting Findings (#3)	Read the 'TSY-1 Design the Big-Picture-to-Detail Narrative' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Tell the Data Story'). Follow its guidance when assisting me. ## Purpose Plan the stakeholder story: reconstructed cycle first (three metrics), then quadrant, then the deficiency register, then stage detail, then starter tabs. Never lead with a detail chart. Do not re-classify Action Register tags. ## Inputs - YAML in `streamlit/data/` (cost_of_delay, ai_opportunities, action_register, promoted_eda). - Template `docs/analysis/narrative-outline.md`. - Skill Data Storytelling and Dashboard Design → Recipe. - Skill Metric Render Catalog (optional pairings; Streamlit tab map). ## Steps 1. Open `docs/analysis/narrative-outline.md`. 2. Opening visual: Delivery cycle (effort, wall-clock, impact). Then opportunity quadrant. Then deficiency register (finding + decision + dE/dK/dI + receiver). Copy CAS; do not invent tags. - dE + automate/delegate → AI SDLC (receiver only). - Other dE → process/tooling. - dK → Team Upskill Engine input (stage, clock, unit, n, role). - dI → staffing. 3. One section per stage in flow order: finding sentence + Action Register decision (or no action). Embed promoted-eda ids or "none". 4. Cap one visual per finding. Name the clock and n. Do not equate issue business days with MR hours. 5. People: name the role (author / integrator / reviewer). Concentration is a risk. 6. If Present Findings uses Streamlit or Jupyter, list starter tabs to instantiate or skip: Commits, Work items, Changes, Pipelines, Load, Defects, Sprints (skill Present Findings with Streamlit → Starter mart tabs). Do not put a tab first. 7. Name the presentation skill (Jupyter = `notebooks/published-findings.ipynb`; Streamlit = mart pages 0–10). ## Done when - Outline lists cycle, quadrant, register, stage sections, and tabs-to-skip. - Duration KPIs state unit, cohort, and n. - Register beat names receivers only. ## Feeds Present Findings.
Present Findings	TSY-2	Tell the Data Story	Delivery Constraint & Opportunity Analysis	Presenting Findings (#3)	Read the 'TSY-2 Present Findings' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Tell the Data Story'). Follow its guidance when assisting me. ## Purpose Build the stakeholder story from the outline. Pick one presentation skill. Do not re-derive numbers. Do not re-classify tags. ## Inputs - `docs/analysis/narrative-outline.md`. - `streamlit/data/.yaml`. - Skills: Present Findings with Jupyter* (`notebooks/published-findings.ipynb`), Present Findings with Streamlit (pages 0–10), QuickSight, Power BI. - Skill Metric Render Catalog. ## Steps 1. Choose one skill. Skip QuickSight if unsubscribed. Skip Power BI if no tenant. Do not add BI in CDK. 2. Order: Delivery cycle → Opportunity quadrant → Deficiency register → Stage detail (promoted_eda only) → starter tabs. 3. Streamlit: pages already in the starter (`0_Delivery_Cycle.py` … `10_Sprints.py`). Browser-verify the path end to end, then each instantiated tab. Skip tabs whose contract views are missing (`tab_pages.py`). If the view exists, run Athena via shared `streamlit/tab_athena.py` — do not leave `print("Instantiate: …")` as the tab body. Pin QueryExecutionId; empty cohort names the window. Live GitHub-only lake: instantiate Commits, Work items (volume only — omit lead/cycle without `jira_status_segments`), Changes (MR hours, not issue days), Pipelines (top failing = workflow name; job-level extract is not in the lake), Load (risk signal). Skip Defects and Sprints unless those views exist. 4. Jupyter: open `notebooks/published-findings.ipynb`, kernel Python (opsdl .venv) (`python -m ipykernel install --user --name opsdl --display-name "Python (opsdl .venv)"`; notebook root = repo). Restart & Run All. Skill 114 recipe matches the cell order. 5. Receivers named only: AI SDLC, process/tooling, Team Upskill Engine (candidates), staffing. No TUE modules. No agent names. 6. Write Published Findings Notebook/Dashboard = the mart URL and/or the notebook path. ## Pitfalls - If `LoginRefreshRequired` / `CreateOAuth2Token` expired → `aws login`, restart kernel, not a Glue/Athena ACL bug. - `streamlit/data/promoted_eda.yaml` `rows: []` is still correct until activity 398 promotes Look-until-Trusted survivors. TSY floor is still cycle + quadrant + deficiency register. Do not dump Metric Render Catalog. Do not treat empty promoted-eda as a bug in this activity. ## Done when - A stakeholder can follow cycle → quadrant → register without a debugging session. - Numbers match the YAML ranking files. - Tags match CAS. Omitted tabs listed as skipped for missing views. ## Feeds Configure Huginn for Automated Reporting. ## Skip Do not open with a single-stage chart or Commits tab. Do not name agents to implement.
Configure Huginn for Automated Reporting	TSY-3	Tell the Data Story	Delivery Constraint & Opportunity Analysis	Presenting Findings (#3)	Read the 'TSY-3 Configure Huginn for Automated Reporting' activity from playbook 'Delivery Constraint & Opportunity Analysis' (workflow 'Tell the Data Story'). Follow its guidance when assisting me. ## Purpose Keep the published story's underlying data current. Huginn has no MCP connector today. ## Inputs - Published Findings (mart URL or notebook). - Skill Huginn Browser Automation → Recipe. - Starter `docs/huginn/README.md`. ## Steps 1. Read `docs/huginn/README.md`. Check sibling `../huginn` for an existing Agent/Scenario. 2. Huginn UI URL is org-specific — record it in playbook notes. Search Scenarios for lake / Athena / Streamlit. 3. Agent type follows the Present Findings surface (HTTP GET of `streamlit_mart_url` from `docs/deploy-manifest.yaml` if Streamlit). Jupyter has no live URL — defer if that was the surface. 4. Dry-run once. Record Agent name, schedule, purpose. 5. Flag as a future MCP-connector candidate. ## Done when - A scheduled refresh exists, or an explicit deferral is written in `docs/huginn/README.md`. ## Skip when `streamlit_mart_url` is empty — defer and say so.
Choose the analysis type	FPM-1	Frame the Problem	EDA with Python, Pandas and Jupyter	Frame the Problem (#1)
Formulate the driving questions	FPM-2	Frame the Problem	EDA with Python, Pandas and Jupyter	Frame the Problem (#1)	Read the 'FPM-2 Formulate the driving questions' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Frame the Problem'). Follow its guidance when assisting me. Write down the specific descriptive question(s) first ("what is happening / what is causing this"), then the predictive/prescriptive question(s) that follow from them ("what do we want to happen / what actions get us there"). Keep the questions in front of you for the rest of the playbook — every later chart and model exists to answer one of them.
Assess analyst readiness	FPM-3	Frame the Problem	EDA with Python, Pandas and Jupyter	Frame the Problem (#1)	Read the 'FPM-3 Assess analyst readiness' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Frame the Problem'). Follow its guidance when assisting me. Before opening any data, check you're bringing genuine interest/curiosity, skepticism, methodical practice, pattern-spotting, and enough domain familiarity to know what "normal" looks like for this data. Also plan to alternate between the statistician, programmer, and domain-expert "hats" as the work proceeds.
Select candidate datasets from the datalake catalog	FPM-4	Frame the Problem	EDA with Python, Pandas and Jupyter	Frame the Problem (#1)	Read the 'FPM-4 Select candidate datasets from the datalake catalog' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Frame the Problem'). Follow its guidance when assisting me. State what the "ideal" dataset for your questions would look like, then browse the provided datalake catalog (a Phainestai-style dataset catalog) for the closest available match(es), accepting a smaller/less feature-rich substitute if the ideal isn't present. Record which catalog entries you selected and why. This step replaces raw web/DB/file acquisition with selection from a pre-built catalog, since this playbook assumes the datalake already exists.
Assess dataset quality against meaningfulness traits	FPM-5	Frame the Problem	EDA with Python, Pandas and Jupyter	Frame the Problem (#1)	Read the 'FPM-5 Assess dataset quality against meaningfulness traits' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Frame the Problem'). Follow its guidance when assisting me. For each selected catalog entry, check it against the traits of meaningful data: sufficient volume, historical depth, consistency over time, multivariate coverage, atomic-level (not pre-aggregated) records, clean values, clear coding, dimensional structure, rich segmentation, and known pedigree/lineage. Drop or flag entries that fail badly on a trait that matters for your questions.
Write the Framing Brief	FPM-6	Frame the Problem	EDA with Python, Pandas and Jupyter	Frame the Problem (#1)	Read the 'FPM-6 Write the Framing Brief' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Frame the Problem'). Follow its guidance when assisting me. Consolidate the chosen analysis type, the driving questions, and the vetted dataset selection into a single short brief. This is the contract the rest of the playbook works against — Phase 2 starts from it, and Phase 2's final conclusions get checked back against it.
Load selected datasets into DataFrames	ODA-1	Organize and Clean Data	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'ODA-1 Load selected datasets into DataFrames' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Organize and Clean Data'). Follow its guidance when assisting me. Read each selected catalog dataset into a pandas Series/DataFrame using the appropriate reader (read_csv with explicit sep/header/index_col/na_values, read_json, read_fwf, or chunked read_csv(chunksize=) for very large extracts). Repair obviously sparse/irregular files (supply explicit `names=`, then `ffill()` a sparse category column before `set_index()`).
Inspect structure	ODA-2	Organize and Clean Data	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'ODA-2 Inspect structure' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Organize and Clean Data'). Follow its guidance when assisting me. Immediately after loading, check `.head()`/`.tail()`, `len()`, `.shape`, `.dtypes`, `.index`, `.columns` (and `.ndim` for any raw numpy arrays). This is the standard first look that catches wrong delimiters, misparsed headers, or unexpected types before you build anything on top of them.
Handle missing and invalid data	ODA-3	Organize and Clean Data	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'ODA-3 Handle missing and invalid data' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Organize and Clean Data'). Follow its guidance when assisting me. Detect gaps with `isnull()`/`notnull()`. Then choose deletion (`dropna()`, whole rows/columns only), imputation (constant/mean via masked assignment, or `fillna(method="ffill"/"bfill")`), selective replacement (`replace()`), or backfill from a secondary source (`combine_first()`) — the right choice depends on domain knowledge about what a gap means for that variable, not a default rule.
Combine and deduplicate datasets	ODA-4	Organize and Clean Data	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'ODA-4 Combine and deduplicate datasets' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Organize and Clean Data'). Follow its guidance when assisting me. If two selected datasets are complementary (different variables, shared key), `pd.merge()`/`.join()` them; if they're similar-schema (same variables, e.g. across time periods or regions), `pd.concat()` them. After any vertical concat, check for and resolve duplicate index labels or rows (`duplicated()`, `drop_duplicates()`).
Reshape data for the framing questions	ODA-5	Organize and Clean Data	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'ODA-5 Reshape data for the framing questions' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Organize and Clean Data'). Follow its guidance when assisting me. Convert between long ("tidy") and wide ("square") layouts with `stack()`/`unstack()`/`pivot()`, and build a hierarchical (multi-index) structure if your questions need more than one categorical grouping key (e.g. State + Year). Choose the shape each later step actually needs rather than leaving everything in whatever shape it was loaded in.
Compute descriptive statistics per candidate variable	EFS-1	Explore and Engineer Features	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'EFS-1 Compute descriptive statistics per candidate variable' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Explore and Engineer Features'). Follow its guidance when assisting me. For every candidate variable, compute sum/mean/median/std/count/min/max (with `skipna`), sort/rank it, and look at cumulative/period-over-period measures (`cumsum`, `diff`) and uniqueness/value_counts for categoricals. This is the "smell and sense of the data" step before you commit to any Y or feature.
Choose candidate target variable(s) Y	EFS-2	Explore and Engineer Features	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'EFS-2 Choose candidate target variable(s) Y' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Explore and Engineer Features'). Follow its guidance when assisting me. From the Framing Brief's questions, pick the concrete column(s) that would answer them if you understood what drove them — this is Y. Note whether Y is continuous (→ regression), categorical/binary (→ classification), or whether there is no single Y and the task is genuinely unsupervised (→ clustering, handled in ACE).
Engineer and derive features	EFS-3	Explore and Engineer Features	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'EFS-3 Engineer and derive features' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Explore and Engineer Features'). Follow its guidance when assisting me. Build the feature table: arithmetic transforms across columns (index-aligned), `groupby()` aggregation to compare Y across categorical breakdowns, `cut()`/`qcut()` to discretize a continuous variable, `get_dummies()` to encode categoricals for models that need numeric input, and `series.map(func)` for one-off custom transforms.
Cross-tabulate categorical candidates against Y	EFS-4	Explore and Engineer Features	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'EFS-4 Cross-tabulate categorical candidates against Y' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Explore and Engineer Features'). Follow its guidance when assisting me. Run `pd.crosstab(feature, Y, margins=True)` for each categorical feature candidate as a cheap first-pass independence check before committing to the heavier correlation/modeling work in the next workflow.
Compute correlation/covariance and significance between features and Y	EFS-5	Explore and Engineer Features	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'EFS-5 Compute correlation/covariance and significance between features and Y' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Explore and Engineer Features'). Follow its guidance when assisting me. Compute pairwise correlation/covariance (`frame.corr()`, `.cov()`, `.corrwith(Y)`) across the feature table, then get significance via `scipy.stats.pearsonr()` since pandas doesn't supply p-values — align mismatched indexes manually first if needed. This produces the ranked candidate feature–Y relationships that Phase 2's ACE workflow will validate.
Interpret correlation with p-value and rule out spurious relationships	ACE-1	Assess Information Gain and Conclude	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'ACE-1 Interpret correlation with p-value and rule out spurious relationships' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Assess Information Gain and Conclude'). Follow its guidance when assisting me. Cross each correlation's sign/magnitude against its p-value (p≤.01 vs not) before treating it as evidence. Remember correlation is not causation — a real correlation may share a hidden confounder — and a non-significant linear correlation doesn't rule out a non-linear relationship.
Design and run a predictive experiment	ACE-2	Assess Information Gain and Conclude	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'ACE-2 Design and run a predictive experiment' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Assess Information Gain and Conclude'). Follow its guidance when assisting me. Split the feature table 70:30 train/test (seed the RNG first). Choose the model by Y's type (per the Target Variable (Y) Definition from EFS): continuous Y → OLS `LinearRegression`, or `Ridge` if predictors are collinear; categorical/binary Y → `LogisticRegression` (use `cut()` first to quantize a continuous proxy into labels if needed, and set `C` well above the default 1.0, e.g. ~20). Fit on training data only, engineering nonlinear predictors (squares/logs/interaction terms) first if a plain linear fit under-captures curvature, then apply the fitted model to the held-out test set. Never touch the test data while fitting.
Evaluate model quality	ACE-3	Assess Information Gain and Conclude	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'ACE-3 Evaluate model quality' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Assess Information Gain and Conclude'). Follow its guidance when assisting me. Build a confusion matrix (classification) or compare predicted-vs-actual on train and test sets (regression); derive accuracy/precision/sensitivity/specificity and choose which one matters for the question at hand. Compare train-set fit against test-set fit to judge overfitting before trusting the model.
Use clustering as an alternative when correlation is weak	ACE-4	Assess Information Gain and Conclude	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'ACE-4 Use clustering as an alternative when correlation is weak' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Assess Information Gain and Conclude'). Follow its guidance when assisting me. When linear correlation is weak or absent but you suspect structure, scale the features (`sklearn.preprocessing.scale()`), run k-means (`KMeans(n_clusters=k)`, k chosen by judgment), and assign human-meaningful labels to the resulting clusters — cluster IDs alone mean nothing.
Rank features by information gain and draw conclusions	ACE-5	Assess Information Gain and Conclude	EDA with Python, Pandas and Jupyter	Explore Data and Find Signal (#2)	Read the 'ACE-5 Rank features by information gain and draw conclusions' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Assess Information Gain and Conclude'). Follow its guidance when assisting me. Fit a Random Forest Regressor on the feature table against Y to get a feature-importance ranking (an ensemble-of-trees estimate of how much each feature actually informs Y), cross-check it against the regression coefficients and correlations from earlier steps, and write the surviving, validated findings as the phase's Conclusions.
Identify the analytical pattern type per conclusion	ECR-1	Encode and Reduce Clutter	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'ECR-1 Identify the analytical pattern type per conclusion' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Encode and Reduce Clutter'). Follow its guidance when assisting me. For each conclusion from Phase 2, classify it as time-series, part-to-whole/ranking, deviation, distribution, correlation, or multivariate before choosing anything about how to draw it — this single classification drives every remaining choice in this workflow and the next.
Select the optimal quantitative scale	ECR-2	Encode and Reduce Clutter	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'ECR-2 Select the optimal quantitative scale' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Encode and Reduce Clutter'). Follow its guidance when assisting me. Bar graphs must start their scale at zero (never narrow it — that's a visual lie); every other chart type (line, scatter, dot plot, box plot) should start a little below the lowest value and end a little above the highest. Begin/end/interval values should all be round numbers.
Add reference lines and regions	ECR-3	Encode and Reduce Clutter	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'ECR-3 Add reference lines and regions' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Encode and Reduce Clutter'). Follow its guidance when assisting me. Whenever a value must be judged against a threshold or norm (budget, target, mean±SD, percentile band), add a labeled reference line or shaded region instead of leaving the comparison to be computed mentally. Set the reference to 0 / 0% / 100% to match whether the deviation is absolute, a percentage difference, or a percentage of the reference.
Choose pre-attentive encodings by precision hierarchy	ECR-4	Encode and Reduce Clutter	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'ECR-4 Choose pre-attentive encodings by precision hierarchy' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Encode and Reduce Clutter'). Follow its guidance when assisting me. Reserve length and 2-D position — the only two pre-attentive attributes perceived with real quantitative precision — for the values that must be compared precisely. Use hue or shape (the best categorical discriminators) to separate groups, and treat size/color-intensity/blur as secondary/tertiary encodings only.
Plan trellis or multi-view layout	ECR-5	Encode and Reduce Clutter	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'ECR-5 Plan trellis or multi-view layout' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Encode and Reduce Clutter'). Follow its guidance when assisting me. If one chart per conclusion would be cluttered, or you need to compare shapes across many groups, plan a trellis/small-multiples grid (one categorical variable) or a visual crosstab (two categorical variables): every panel must share the same chart type, size and scale, sequenced by magnitude rather than alphabetically. For open-ended exploration, plan tightly-coupled multiple views with shared filtering/brushing instead of one fixed chart.
Reduce over-plotting	ECR-6	Encode and Reduce Clutter	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'ECR-6 Reduce over-plotting' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Encode and Reduce Clutter'). Follow its guidance when assisting me. If points visibly collide in a scatter or dense line chart, apply remedies in order of increasing intervention: shrink point size → remove fill (outline only) → change shape → jitter → add transparency → encode density (contours/heatmap cells) → reduce the data itself (aggregate, filter, trellis, or sample). Stop at the mildest remedy that solves the problem.
Check for spurious or missed patterns	ECR-7	Encode and Reduce Clutter	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'ECR-7 Check for spurious or missed patterns' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Encode and Reduce Clutter'). Follow its guidance when assisting me. Before locking in the encoding plan, verify every apparent pattern against the underlying detail data, and deliberately look again with fresh eyes for a real pattern you may have missed. This is the QA gate before any chart gets built.
Design a time-series display	CTE-1	Choose Chart per Analysis Type	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'CTE-1 Design a time-series display' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Choose Chart per Analysis Type'). Follow its guidance when assisting me. Default to a line graph for continuous change through time; use bars for period-to-period comparison, a dot plot (never connected by a line) for irregularly-spaced samples, box plots to show a distribution shifting over time, and radar/cycle plots or heatmaps for cyclical/high-volume data. Smooth volatility with a running average rather than a single trend line, use a log scale or % change when comparing growth rates of very different magnitude, and never render a missing value as zero — break the line instead.
Design a part-to-whole/ranking display	CTE-2	Choose Chart per Analysis Type	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'CTE-2 Design a part-to-whole/ranking display' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Choose Chart per Analysis Type'). Follow its guidance when assisting me. Sort items by value and use a bar graph (never a pie chart) for ranking/part-to-whole comparison; switch to a dot plot when the scale must be narrowed off zero; use a Pareto chart (bars + cumulative-% line) for 80/20 analysis; re-express with √ (mildest), then log, then inverse when values span a huge range; use a line graph only to show rank changes over time (a bumps chart), never a single ranking snapshot.
Design a deviation display	CTE-3	Choose Chart per Analysis Type	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'CTE-3 Design a deviation display' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Choose Chart per Analysis Type'). Follow its guidance when assisting me. Pair a bar or line graph with a 0 / 0% / 100% reference line depending on whether the deviation (actual vs. budget/target/forecast/prior period/peer) is shown as an absolute difference, a percentage difference, or a percentage of the reference value. Use bars to emphasize individual-period deviations and lines when the overall shape of deviation through time matters more.
Design a distribution display	CTE-4	Choose Chart per Analysis Type	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'CTE-4 Design a distribution display' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Choose Chart per Analysis Type'). Follow its guidance when assisting me. For a single distribution use a histogram (shape+magnitude, consistent bin widths, bin count tuned by trial and error), a frequency polygon (shape only), a strip plot (every raw value, small N), or a stem-and-leaf plot (≤100 values, quick by hand). For comparing several distributions, box plots beat everything else — add outlier dots beyond the whiskers rather than stretching them. Prefer median/percentiles over mean/SD when outliers are present.
Design a correlation display	CTE-5	Choose Chart per Analysis Type	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'CTE-5 Design a correlation display' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Choose Chart per Analysis Type'). Follow its guidance when assisting me. Use a scatterplot with a square aspect ratio, both axes trimmed near min/max, for two variables; add a trend line matching the actual shape (linear/logarithmic/exponential/low-order polynomial — never an overfit high-order polynomial), with a separate trend line per subgroup if slopes visibly differ. For 3+ variables use a scatterplot matrix, table lens, or parallel-coordinates plot; de-clutter dense scatterplots (transparency/jitter) and add grid lines when comparing several side by side.
Design a multivariate display	CTE-6	Choose Chart per Analysis Type	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'CTE-6 Design a multivariate display' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Choose Chart per Analysis Type'). Follow its guidance when assisting me. Avoid glyph-based displays (Chernoff faces, stars, whiskers) — no demonstrated real-world effectiveness. Prefer a parallel-coordinates plot with brushing/filtering, or a colorblind-safe diverging-color heatmap (never red/green, never black as the "near zero" color), to compare multivariate profiles. Use a clustering/similarity-ranking algorithm, not eyes alone, to group items, then visualize the groups (e.g. in a trellis).
Sequence the narrative	SNK-1	Storyboard the Notebook	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)
Draft one storyboard entry per chart	SNK-2	Storyboard the Notebook	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'SNK-2 Draft one storyboard entry per chart' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Storyboard the Notebook'). Follow its guidance when assisting me. For every chart in the sequence, write down: chart type (from CTE), axis/scale choice and reference lines (from ECR), any trellis/layout decision, and the one-sentence insight/conclusion it must support. This entry-per-chart table is the literal blueprint Phase 4 codes against.
Review the storyboard against conclusions	SNK-3	Storyboard the Notebook	EDA with Python, Pandas and Jupyter	Design the Visual Story (#3)	Read the 'SNK-3 Review the storyboard against conclusions' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Storyboard the Notebook'). Follow its guidance when assisting me. Check the storyboard against Phase 2's Conclusions Summary: does every conclusion that matters have a designated chart, and does every planned chart trace back to a real conclusion (not just an interesting-looking variable)? Fix gaps before writing any Plotly code.
Set up the Plotly/Jupyter environment	IVS-1	Implement Plotly Visuals	EDA with Python, Pandas and Jupyter	Build the Story in Plotly (#4)	Read the 'IVS-1 Set up the Plotly/Jupyter environment' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Implement Plotly Visuals'). Follow its guidance when assisting me. Import `plotly.express as px` and `plotly.graph_objects as go`, set the notebook renderer (`pio.renderers.default = "notebook"` or "notebook_connected"), and decide once whether figures need to be interactive (keep Plotly) or also exported statically (`kaleido` for PNG/PDF export).
Implement each storyboard entry as a Plotly figure	IVS-2	Implement Plotly Visuals	EDA with Python, Pandas and Jupyter	Build the Story in Plotly (#4)	Read the 'IVS-2 Implement each storyboard entry as a Plotly figure' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Implement Plotly Visuals'). Follow its guidance when assisting me. Map each storyboard chart type to Plotly: time-series → `px.line`/`go.Scatter(mode="lines")`; part-to-whole/ranking → `px.bar` (sorted, never `px.pie`) or `px.scatter` for a dot plot; deviation → `px.bar`/`px.line` plus a reference shape; distribution → `px.histogram`, `px.box`, or `px.strip`; correlation → `px.scatter` with `trendline="ols"/"lowess"`; multivariate → `px.imshow` (diverging colorscale) or `px.parallel_coordinates`. Use the exact chart type the storyboard specifies — do not substitute a "nicer-looking" one.
Apply scale/reference-line/annotation rules via layout methods	IVS-3	Implement Plotly Visuals	EDA with Python, Pandas and Jupyter	Build the Story in Plotly (#4)	Read the 'IVS-3 Apply scale/reference-line/annotation rules via layout methods' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Implement Plotly Visuals'). Follow its guidance when assisting me. Enforce ECR's decisions in code: `fig.update_yaxes(rangemode="tozero")` for bar charts, explicit `range=[min,max]` with round numbers for line/scatter/box; `fig.add_hline()`/`add_vline()`/`add_shape()` for reference lines/regions and target bands; `fig.update_traces(marker=dict(opacity=...))` or `size=` for over-plotting fixes (jitter via manual x/y offset, density via `px.density_heatmap`).
Build trellis/small-multiples and multi-view linking	IVS-4	Implement Plotly Visuals	EDA with Python, Pandas and Jupyter	Build the Story in Plotly (#4)	Read the 'IVS-4 Build trellis/small-multiples and multi-view linking' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Implement Plotly Visuals'). Follow its guidance when assisting me. Use `facet_col=`/`facet_row=` (with `facet_col_wrap=`) in plotly.express for trellis/visual-crosstab layouts, keeping `category_orders=` set to sort panels by magnitude rather than alphabetically; use `plotly.subplots.make_subplots` for hand-built multi-panel layouts; for linked brushing/filtering across views, use `go.FigureWidget` in the notebook or export to Dash if true cross-filtering is required.
Assemble the Jupyter storybook notebook	IVS-5	Implement Plotly Visuals	EDA with Python, Pandas and Jupyter	Build the Story in Plotly (#4)	Read the 'IVS-5 Assemble the Jupyter storybook notebook' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Implement Plotly Visuals'). Follow its guidance when assisting me. Interleave a markdown cell (the question/insight from the storyboard) before each code cell that renders its Plotly figure, in the sequence fixed by SNK. Keep one figure's setup self-contained per cell group so the notebook can be read top-to-bottom as the story, not just executed.
Review and export the final notebook/report	IVS-6	Implement Plotly Visuals	EDA with Python, Pandas and Jupyter	Build the Story in Plotly (#4)	Read the 'IVS-6 Review and export the final notebook/report' activity from playbook 'EDA with Python, Pandas and Jupyter' (workflow 'Implement Plotly Visuals'). Follow its guidance when assisting me. Re-run the notebook top-to-bottom on a clean kernel to confirm every cell executes and every chart still matches its storyboard entry and conclusion. Export to HTML (`jupyter nbconvert --to html`) or PDF for the data sponsor, alongside the notebook itself, per the Framing Brief's audience.
Assign the Delivery Manager	BTM-1	Bootstrap the Team	Junior Edda	Kickoff (#0)	Read the 'BTM-1 Assign the Delivery Manager' activity from playbook 'Junior Edda' (workflow 'Bootstrap the Team'). Follow its guidance when assisting me. ## Objective Have the project sponsor appoint the Delivery Manager before the Delivery Manager performs any project work. An AI agent must not appoint itself or infer a person. ## Procedure 1. Obtain the sponsor's explicit appointment. 2. Record it in `docs/project/DELIVERY_OWNERSHIP.md` with: - Delivery Manager name and contact; - start date and timezone; - decision authority and approval boundaries; - escalation route and response expectation; - backup/delegate; - responsibility for Charter ownership, cadence, AIN oversight, and Risk/Problem tickets. 3. Confirm the appointee accepts the role. 4. If no person is available, record the sponsor as interim DM with an expiry/review date; do not leave ownership implicit. ## Completion evidence The assignment record exists, names both sponsor and DM, contains authority boundaries, and includes appointment and acceptance timestamps. Staffing is a human/sponsorship action; the activity deliberately has no executing Mimir Agent.
Absorb Vision/Scope Handover	BTM-2	Bootstrap the Team	Junior Edda	Kickoff (#0)	Read the 'BTM-2 Absorb Vision/Scope Handover' activity from playbook 'Junior Edda' (workflow 'Bootstrap the Team'). Follow its guidance when assisting me. ## Objective Normalize validated business evidence into `docs/project/VISION_SCOPE_HANDOVER.md`, the single handoff consumed by Charter drafting and ESM. ## Required external inputs Use the latest approved outputs from Testing a Business Idea when that playbook was run: Customer and USP Dossier, Experiment/Test Charter, Approved Learning Card, Feasibility Decision, and Recommended Next Experiment. The external playbook currently ends at Approve the Learning and Decision; do not look for a nonexistent activity named “Prepare handover package for Junior Edda.” Equivalent sponsor-approved evidence may be used when Testing a Business Idea was not run. ## Procedure 1. Inventory each source with title, version/date, owner, and location. 2. Fail fast if there is no approved feasibility decision or if the decision is `stop`. An `adapt` decision must state the approved adaptation before continuing. 3. Extract: target customer/personas; jobs/pains/gains; USP; observed evidence; assumptions; product scope; excluded scope; constraints; success/failure criteria; outstanding risks; recommended next step. 4. Preserve provenance. Label every item `observed`, `approved decision`, or `assumption`. 5. Reconcile contradictions with the sponsor; do not silently choose one source. 6. Write the normalized document and an unresolved-questions table with owner and due date. ## Completion evidence The handover exists at the canonical path, cites every source, contains an explicit continue/adapt decision, distinguishes evidence from assumptions, and has no ownerless blocker. Record its version and approval.
Draft Charter v0	BTM-3	Bootstrap the Team	Junior Edda	Kickoff (#0)	Read the 'BTM-3 Draft Charter v0' activity from playbook 'Junior Edda' (workflow 'Bootstrap the Team'). Follow its guidance when assisting me. ## Objective Create the executable project-management contract at `docs/project/CHARTER.md` from the normalized handover. Charter v0 must be approved before Inception starts. ## Plan first Enter the ADE's planning mode when available. Otherwise write a step-by-step drafting plan. Sections may be drafted in parallel only when each worker writes a separate section and one final worker checks cross-section consistency. ## Required structure 1. Goals — outcome, measure, target, target date, evidence source, owner. 2. Team Roster — person/agent, mission, authority, owned workflows/artifacts, meetings, backup. Include team maturity: `L2 \| early-L3 \| late-L3 \| L4`, supporting evidence, assessor, and assessment date. 3. Variables We Track — one row per stable `variable_id` with definition, unit, source system, exact query/command, aggregation/window, freshness limit, Green/Yellow/Orange/Red or Green/Red thresholds, missing-data behavior, owner, and `gating_policy: observe \| pause_new_work \| block_release`. 4. Artifact Coverage Decision — artifact, required?, canonical path/system, owner, freshness rule, validation command. 5. Cadence — current iteration-length decision process, ceremonies, participants, trigger, duration; recurring meetings only when team size is greater than one. 6. Release Roadmap — alpha/beta/gamma/RC, explicitly marked aspirational until EST validates it. ## Procedure and gates - Cite every statement back to the Vision/Scope Handover or label it as an assumption. - Use stable IDs for variables and artifacts; display names may change without breaking history. - Define `Unknown` handling separately from performance bands. Missing/stale evidence is never Green. - Obtain explicit sponsor and Delivery Manager approval. ## Completion evidence All six sections exist; every variable is mechanically measurable; every required artifact is locatable and testable; maturity has evidence; gating policies are explicit; the roadmap is labeled aspirational; approval and version `v0` are recorded.
Run ESM with Client, Walk Mockups	BTM-4	Bootstrap the Team	Junior Edda	Inception (#1)	Read the 'BTM-4 Run ESM with Client, Walk Mockups' activity from playbook 'Junior Edda' (workflow 'Bootstrap the Team'). Follow its guidance when assisting me. ## Objective Invoke the existing Envision the System (ESM) workflow with the client and establish the approved product/experience baseline for architecture and delivery. ## Required inputs - `docs/project/VISION_SCOPE_HANDOVER.md`. - `docs/project/CHARTER.md` v0, especially Goals and Team Roster. - Named client decision-maker and scheduled review point. ## Procedure 1. Enter the ADE's planning mode when available; otherwise write a short execution plan before changing artifacts. 2. Invoke ESM activities in their defined dependency order. Pass the normalized handover, Charter goals, personas, constraints, and unresolved assumptions as context. 3. Where ESM explicitly permits fan-out, parallelize independent read-only analysis or distinct-output work, then run its convergence checks. 4. Walk every mockup and material journey decision with the client. Record decisions, rejected alternatives, and open questions. 5. Resolve or explicitly defer blocking questions before handing off to DTA. ## Completion evidence All required ESM artifacts exist at their canonical project locations, identifiers agree across journey/IA/dialogue/feature/mockup artifacts, the client approval record names the approved baseline, and no unresolved question prevents architecture. Merely generating mockups does not complete this activity.
Complete Inception and Elaboration	BTM-5	Bootstrap the Team	Junior Edda	Elaboration (#2)	Read the 'BTM-5 Complete Inception and Elaboration' activity from playbook 'Junior Edda' (workflow 'Bootstrap the Team'). Follow its guidance when assisting me. ## Objective Carry the approved ESM baseline through the existing Inception and Elaboration workflows until the repository is ready for automated assessment and the first Construction iteration. ## Procedure 1. Verify Workflow Envision the System (ESM) completed and its client approvals are recorded. 2. Run Define Architecture (DTA) and approve the resulting SAO. 3. Run Deploy Software Process (DSP). 4. After DSP prerequisites are satisfied, run Estimate the Project (EST) and Design & Deploy Cloud Infra (DCI) in parallel when their read/write footprints do not conflict. If the ADE supports parallel workers, dispatch one bounded worker per workflow and converge on cost, environment, and release assumptions. 5. Run Design & Deploy CI/CD (DCD) after DCI. 6. Run Bootstrap Project (BSP) after DCD. 7. Execute the phase-appropriate Test Automation Framework (TFK) activities required before the first feature. 8. At convergence, verify that SAO, process configuration, estimates, runnable repository, test commands, deployment path, rollback path, and required secrets/contracts agree. ## Failure handling Stop at the first failed workflow gate. Do not skip a dependency because another worker finished. Do not claim readiness from generated files alone; execute the repository's documented verification commands and inspect the target environment where applicable. ## Completion evidence Create `docs/project/ELABORATION_READINESS.md` listing each invoked workflow, its authoritative output, verification command/result, unresolved risk, and approval. Every required row must be PASS before Set Up Huginn begins.
Set Up Huginn	BTM-6	Bootstrap the Team	Junior Edda	Elaboration (#2)	Read the 'BTM-6 Set Up Huginn' activity from playbook 'Junior Edda' (workflow 'Bootstrap the Team'). Follow its guidance when assisting me. ## Objective Configure Huginn to execute the AIN assessment contract manually and, when appropriate, on a schedule. Huginn observes and reports; it does not redefine Charter variables or bypass delivery gates. ## Required inputs - Approved Charter v0 at `docs/project/CHARTER.md`. - A runnable repository with its delivery/test commands. - Completed Inception and Elaboration readiness evidence. - A selected GH or Jira ticket adapter and credentials supplied through the project's approved secret mechanism. ## Procedure 1. Inspect existing Huginn configuration and repository automation before creating anything. 2. Create `docs/project/HUGINN_ASSESSMENT_CONTRACT.md` containing: - repository and environment identity; - manual trigger and schedule; - exact source/query/command for every Charter variable; - assessment snapshot boundary and freshness limit; - ticket system, project/repository, labels/types, and stable concern key; - expected-artifact paths and staleness checks; - notification and escalation destinations; - retry, timeout, and overlapping-run policy. 3. Configure one AIN run at a time per project. A second trigger must reuse or wait for the active run, not race it. 4. Run AIN once manually against known data. 5. Verify the persisted Assessment Run Record, ticket action, throughput result, coverage result, and final report. 6. Enable scheduling only after the manual run passes. ## Failure handling If a source, credential, query, or ticket adapter is missing, record the exact blocker and stop. Never substitute invented data or mark an unmeasurable variable Green. ## Completion evidence The contract is committed, a manual run has a stable run ID and complete report, all side effects are idempotent, and the next scheduled time is visible when scheduling is enabled.
Run First Iteration, Ship Increment	BTM-7	Bootstrap the Team	Junior Edda	Construction (#3)	Read the 'BTM-7 Run First Iteration, Ship Increment' activity from playbook 'Junior Edda' (workflow 'Bootstrap the Team'). Follow its guidance when assisting me. ## Objective Run the first complete delivery cycle with the team and ship one bounded, accepted increment while the Charter assumptions are still provisional. ## Preconditions - Charter v0 is approved. - ESM, DTA, DSP, required estimation/infrastructure/CI-CD work, BSP, and applicable test-framework setup are complete. - Huginn can run AIN manually even if scheduling is not yet enabled. - One candidate goal can fit the cadence selected by RIN. ## Procedure 1. Invoke Workflow Run the Iteration (RIN); do not duplicate its activities here. 2. Keep the Delivery Manager and team together for this first pass. Record every place where the Charter, tooling, ownership, or activity guidance is insufficient. 3. When RIN starts MIN, launch or schedule Assess the Iteration (AIN) as the independent supervisory stream. If the ADE supports subagents/background tasks, keep AIN separate from the MIN execution context. 4. Preserve every PIN/MIN human gate. Parallel execution does not authorize merging, releasing, purchasing, or changing scope. 5. Ship only when the selected increment passes its declared acceptance, regression, and release checks. ## Completion evidence Record the iteration goal, manifest/milestone, release or deployment identifier, acceptance result, latest AIN report, unresolved tickets, and observed process defects. A plan without a shipped and verified increment does not complete this activity.
Hold Retrospective, Update Charter	BTM-8	Bootstrap the Team	Junior Edda	Construction (#3)	Read the 'BTM-8 Hold Retrospective, Update Charter' activity from playbook 'Junior Edda' (workflow 'Bootstrap the Team'). Follow its guidance when assisting me. ## Objective Close the first shipped iteration, test the assumptions in Charter v0 against observed evidence, and publish an approved Charter v1. ## Required inputs - `docs/project/CHARTER.md` at v0. - The first iteration goal, manifest, release evidence, and Definition-of-Done result. - The latest Iteration Assessment Report and all open Risk/Problem tickets. - Any Iteration Improvement Proposals (IIPs). - Participants from the Charter Team Roster. ## Procedure 1. Create `docs/project/retros/BOOTSTRAP_RETRO.md`. 2. Record what was expected, what happened, evidence, and consequences. Separate facts from opinions. 3. Review every Charter section: - goals and success measures; - roster, authority, and ownership; - team maturity classification and its evidence; - tracked-variable measurement contracts and thresholds; - required-artifact coverage; - meeting cadence; - aspirational roadmap. 4. Review each IIP. Record `accepted`, `rejected`, or `deferred`, with owner and reason. 5. Update `docs/project/CHARTER.md` to v1. Add a dated change log; never silently overwrite v0 assumptions. 6. Obtain explicit sponsor/Delivery Manager approval. ## Completion evidence - Bootstrap retrospective exists and cites iteration evidence. - Charter says `Version: 1`, contains the dated diff, and has no undefined variable source, threshold, owner, or gating policy. - Every IIP and open Risk/Problem ticket has a disposition or named owner. - Approval is recorded. Do not declare Bootstrap complete without it.
Establish Conventions	ESM-1	Envision the System	Junior Edda	Inception (#1)	Read the 'ESM-1 Establish Conventions' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. # Establish Conventions ## Objective Establish the foundational conventions and standards that will be used throughout the entire UX design-to-development process. This includes the Screen ID naming convention for traceability and other important guidelines. --- ## Screen ID Convention (Traceability) All screens must follow a consistent naming pattern for end-to-end traceability. ### Format: `FOB-{ENTITY}-{OPERATION}-{VERSION}` Components: - `FOB` = Forward Operating Base (the web UI) - `{ENTITY}` = Uppercase entity name (PLAYBOOKS, WORKFLOWS, ACTIVITIES, etc.) - `{OPERATION}` = Screen operation type (see CRUDLF patterns below) - `{VERSION}` = Version number (usually `-1` for MVP) ### CRUDLF Operations Standard CRUD + List/Find pattern: - `LIST+FIND` - Entry point screen for entity (list view with search/filter) - `CREATE_{ENTITY}` - Creation form screen - `VIEW_{ENTITY}` - Detail/read-only view screen - `EDIT_{ENTITY}` - Edit form screen - `DELETE_{ENTITY}` - Deletion confirmation screen Examples: - `FOB-PLAYBOOKS-LIST+FIND-1` → Playbooks list with search/filter - `FOB-PLAYBOOKS-CREATE_PLAYBOOK-1` → Create new playbook form - `FOB-PLAYBOOKS-VIEW_PLAYBOOK-1` → View playbook details - `FOB-PLAYBOOKS-EDIT_PLAYBOOK-1` → Edit playbook form - `FOB-PLAYBOOKS-DELETE_PLAYBOOK-1` → Delete playbook confirmation - `FOB-WORKFLOWS-LIST+FIND-1` → Workflows list (within playbook) - `FOB-HOWTOS-CREATE_HOWTO-1` → Create howto form ### Traceability Chain Every Screen ID must appear in ALL of these artifacts: 1. User Journey (`docs/features/user_journey.md`) - Format: `#### Screen: FOB-{ENTITY}-{OPERATION}-{VERSION}` - Describes layout, actions, user flow 2. Screen Flow Diagram (`docs/ux/2_dialogue-maps/screen-flow.drawio`) - Box label: `FOB-{ENTITY}-{OPERATION}-{VERSION}` - Bold border for LIST+FIND entry points - Navigation arrows between screens 3. Feature File (`docs/features/act-X-{entity}/{entity}-{operation}.feature`) - Feature title: `Feature: FOB-{ENTITY}-{OPERATION}-{VERSION} {Description}` - Scenario IDs: `FOB-{ENTITY}-{OPERATION}-{NN}` (01, 02, 03...) - File naming: `{entity}-{operation}.feature` (kebab-case) 4. Template (`templates/{entity}/{operation}.html`) - HTML comment: `<!-- Screen: FOB-{ENTITY}-{OPERATION}-{VERSION} -->` - Hidden div: `<div data-testid="{entity}-{operation}-loaded" style="display: none;">{SCREEN_ID}</div>` - Enables grep discovery: `grep -r "FOB-PLAYBOOKS-LIST+FIND-1" .` 5. Tests (`tests/integration/test_{entity}_{operation}.py`) - Test names reference Screen ID - Docstrings include Screen ID ### Benefits ✅ Bidirectional Traceability: Navigate from code → design or design → code ✅ Quick Discovery: `grep -r "FOB-PLAYBOOKS-LIST+FIND-1" .` finds all related artifacts ✅ Consistency Validation: Verify all screens have complete documentation ✅ Onboarding: New developers can trace any screen to design intent ✅ Gap Detection: Missing Screen IDs indicate incomplete UX work --- ## Important Notes ### What NOT to Do - ❌ Do NOT create .MD files unless explicitly part of task definition, workflow, or rule - ❌ Do NOT skip the planning step - always show plan and get approval - ❌ Do NOT create massive documents or commits in one go - ❌ Do NOT declare features complete with failing tests - ❌ Do NOT mock in integration tests - ❌ Do NOT skip accessibility attributes or tooltips - ❌ Do NOT use vague naming or generic values in scenarios ### What TO Do - ✅ Follow plan-then-do at every step - ✅ Work incrementally - small vertical slices - ✅ Write tests before implementation - ✅ Maintain 100% test pass rate - ✅ Use existing patterns and conventions - ✅ Prioritize accessibility (ARIA, semantic HTML, keyboard navigation) - ✅ Ensure testability (`data-testid` on all interactive elements) - ✅ Validate diagrams visually with human eye - ✅ Add Font Awesome Pro icons and Bootstrap tooltips to all buttons - ✅ Check for existing GitHub issues before creating new ones - ✅ Commit after each major step with Angular convention --- ## Deliverables - ✅ Screen ID convention understood and documented - ✅ Traceability chain requirements clear - ✅ Important guidelines reviewed - ✅ Ready to proceed with User Journey definition
Define User Journey	ESM-2	Envision the System	Junior Edda	Inception (#1)	Read the 'ESM-2 Define User Journey' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. # Define User Journey ## Objective Establish the high-level user experience narrative with personas, user flows, and screen descriptions. ## Artifacts Created - `docs/features/user_journey.md` - Complete user journey narrative ## Process ### 1. Write User Journey Document - Define personas (e.g., Mike Chen, Maria Rodriguez) - Map out Acts (Act 0: Authentication → Act 9: PIPs, etc.) - Describe user goals, motivations, and context for each Act - Identify key screens and user flows - Document system architecture notes (FOB vs HB, MCP integration) - Follow narrative structure: Context → Screen → Actions → Results Template: ```markdown ### Act X: [ENTITY] - Complete CRUDLF Context: [User situation and needs] Pattern: [Entity] follows the standard CRUDLF pattern with LIST+FIND as the entry point. #### Screen: FOB-[ENTITY]-LIST+FIND-1 [User] clicks "[Entity]" in the main navigation. The [entity] list page appears: Layout: - Header: "[Entity]" with count badge (e.g., "[Entity] (3)") - Top Actions: - [Create New [Entity]] button (primary action, bold blue) - [Additional Action] button - Search & Filter Section: - Search box: "Find [entity]..." (searches [fields]) - Filters: [Filter1], [Filter2], [Filter3] - [Clear Filters] button - [Entity] Table with columns: - [Column1] \| [Column2] \| [Column3] \| Actions - Sort by any column - Row Actions (dropdown menu per [entity]): - [View] - Opens FOB-[ENTITY]-VIEW_[ENTITY] - [Edit] - Opens FOB-[ENTITY]-EDIT_[ENTITY] - [Delete] - Opens FOB-[ENTITY]-DELETE_[ENTITY] modal - [...More] - Additional actions - Empty State (if no [entity]): - Illustration: [Description] - "No [entity] yet" - "[Call to action message]" - [Action Buttons] - Pagination: Shows 20 per page with page controls Example Data: - "[Example 1]" \| [Data] \| [Data] \| [Status] - "[Example 2]" \| [Data] \| [Data] \| [Status] [User] sees [description of what user can do]. ``` ## How to Execute This Step ### 1. Plan Before Executing (plan-then-do) - Identify all affected documents, sections, and artifacts - Figure out what content you need and what's available to reference - Note what needs to be created from scratch - ALWAYS show the plan and ask for approval or refinements - Execute the plan, adjusting as necessary based on discoveries - After every major section, update the plan and explain next step ### 2. Work Incrementally (small-increments) - Work section-by-section (one Act at a time for user journey) - After every change: write → review → refine → evaluate - No massive documents created in one go - Build incrementally: personas → Act 0 → Act 1 → Act 2, etc. ## Deliverables - ✅ Complete user journey with all Acts documented - ✅ Each screen uses Screen ID format: `#### Screen: FOB-{ENTITY}-{OPERATION}-{VERSION}` - ✅ Screen IDs follow CRUDLF pattern: LIST+FIND, CREATE_{ENTITY}, VIEW_{ENTITY}, EDIT_{ENTITY}, DELETE_{ENTITY} - ✅ Entry point screens (LIST+FIND) clearly marked - ✅ Screen IDs are unique and traceable
Define Information Architecture	ESM-3	Envision the System	Junior Edda	Inception (#1)	Read the 'ESM-3 Define Information Architecture' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. # Define Information Architecture ## Objective Establish the design system foundation, layout patterns, and component standards. ## Artifacts Created - `docs/ux/IA_guidelines.md` - Information architecture and design system ## Process ### 1. Define Information Architecture - Document design system foundation (Bootstrap 5.3+ base) - Define design tokens (colors, spacing, typography, shadows, borders) - Establish layout patterns (2-column, 3-column, grid, forms) - Define navigation structure (top navbar, breadcrumbs, tabs) - Document component patterns (cards, buttons, forms, modals) - Specify accessibility requirements - Define icon system (Font Awesome Pro) Philosophy: Leverage Bootstrap's conventions, utilities, and component patterns as the first choice. Customize only when necessary for brand identity or specific user experience requirements. ### Key Sections to Document #### 1. Design Tokens - Color palette (primary, secondary, custom colors) - Spacing scale (Bootstrap multipliers) - Typography (font stacks, sizes, weights) - Shadows and borders #### 2. Layout Patterns - Dashboard grids - Form layouts - List/table views - Detail pages #### 3. Navigation Design - Top navigation structure - Breadcrumbs - Tab navigation - Active states and ARIA attributes #### 4. Component Patterns - Cards - Buttons (with Font Awesome icons and tooltips) - Forms and inputs - Modals and dialogs - Tables - Empty states #### 5. Page Header Pattern Document the canonical structure for every non-dashboard page: breadcrumb row, title + action cluster row, and (for detail pages) a metadata sub-row. Specify which information belongs in each row, how the action cluster is composed, and how it adapts between list, view, and edit contexts. #### 6. Baseline CRUDLF Page Templates Document the skeleton layout for each standard screen operation: List+Find, View, Edit, and Delete. For each, specify the column split, which organisms compose the main area, what the sidebar (if any) may contain, and whether the operation uses a full page or a modal. #### 7. Button Placement Rules Document as a decision table: for each context (list page header, form footer, detail page with destructive action, modal footer) — which corner holds the action cluster, and what is the left-to-right order of buttons within it. State the universal rules that apply across all contexts (e.g. primary always rightmost; destructive always leftmost in its cluster). #### 8. Feedback / Notification System Document the chosen mechanism for each feedback type: success, error, warning, info, and field validation. For each, specify the UI component used, its positioning, dismissal strategy (auto-dismiss with timing vs. manual), and how backend operations surface feedback to the frontend (e.g. response headers, HTMX events, Django messages framework). #### 9. Component State Catalogue For every interactive component, document all states: default, hover, focus, active, disabled, and loading. List the minimum set of components that must be covered. Specify the visual treatment (CSS class, style change, or animation) for each state and note any accessibility requirements (e.g. visible focus ring, aria-disabled). ## How to Execute This Step ### 1. Plan Before Executing - Identify all design system components needed - Reference existing Bootstrap documentation - Note Mimir-specific customizations - Show plan and get approval ### 2. Work Incrementally - Document one section at a time - After every section: write → review → refine - Build incrementally: tokens → layouts → navigation → components → page patterns → CRUDLF templates → button rules → feedback → states ## Deliverables - ✅ IA guidelines with design system specifications - ✅ Screen ID convention documented: Format, CRUDLF operations, examples - ✅ Navigation structure defined - ✅ Layout patterns documented - ✅ Component patterns with accessibility requirements - ✅ Icon system (Font Awesome Pro) documented - ✅ Bootstrap customization approach clear - ✅ Page header pattern documented (breadcrumb / title + action cluster / metadata sub-row) - ✅ Baseline CRUDLF templates documented (List+Find, View, Edit, Delete) - ✅ Button placement rules table documented - ✅ Feedback system documented (mechanism and dismissal strategy per feedback type) - ✅ Component state catalogue documented (all states for all required components) --- ## Responsive Coverage Contract Responsive support is an explicit design and verification contract, not a generic instruction to "make it responsive." Define all dimensions in CSS viewport pixels used by the browser test context. ### Required viewport matrix \| Profile \| Viewport \| Bootstrap width tier \| Design risk \| \|---\|---:\|---\|---\| \| Wide, low-height desktop \| `1280 x 800` \| `xl` \| Limited vertical space despite desktop width \| \| Large 16:9 desktop \| `1920 x 1080` \| `xxl` \| Excess width and long line lengths \| \| 14-inch MacBook Pro reference \| `1512 x 982` \| `xxl` \| Laptop-density layout \| \| 9.7-inch iPad portrait \| `768 x 1024` \| `md` \| Tablet stacking and touch targets \| \| 9.7-inch iPad landscape \| `1024 x 768` \| `lg` \| Wide but vertically constrained tablet \| \| Representative phone portrait \| `390 x 844` \| `xs` \| Primary phone layout \| \| Minimum supported phone portrait \| `360 x 800` \| `xs` \| Narrow-phone boundary \| The IA may add project-specific profiles but must not silently remove or weaken these baselines. Device pixel ratio, physical panel resolution, and device marketing names do not replace the CSS viewport dimensions. ### Page-layout recipes Define reusable responsive recipes for every page archetype used by the Screen Flow, including dashboards, LIST+FIND tables, entity VIEW pages, collection VIEW pages, create/edit forms, delete/confirmation surfaces, split-pane or canvas screens, and full-viewport screens. Each recipe specifies, for every target viewport or applicable width/height class: - container width, columns, and stacking order; - navigation collapse and breadcrumb behavior; - title, metadata, and action-cluster wrapping; - table/card transformation and intentional local overflow; - sidebar, context rail, split-pane, canvas, modal, and drawer behavior; - readable line length and use of surplus width; - vertical scrolling, sticky regions, and primary-action reachability on low-height screens; - touch-target, focus-order, and keyboard behavior. Every Screen ID must map to one named page-layout recipe. A screen that behaves differently must document the exception at each affected viewport. Mapping to a shared recipe is an explicit layout definition and does not require unique CSS for every page. ### Universal visual acceptance rules At every target viewport: - no unintended page-level horizontal scrollbar appears; - text, controls, menus, tooltips, modals, and feedback are not clipped or overlapped; - primary navigation and the screen's primary action remain reachable; - reading order and keyboard focus order remain coherent after stacking or collapse; - tables and other intentionally scrollable components contain overflow inside their documented wrapper; - content remains readable without browser zoom; - low-height layouts permit deliberate vertical scrolling unless the documented recipe is full-viewport, in which case the viewport-fit behavior is tested explicitly. ### Evidence and traceability The IA Guidelines contain the viewport matrix and recipe catalogue. Maintain a coverage table mapping every Screen ID to its recipe and any exception scenarios. ESM mockups and BPE journey tests use the same profile names and dimensions so design evidence, Gherkin, screenshots, and implementation results remain traceable.
Create Dialogue Maps	ESM-4	Envision the System	Junior Edda	Inception (#1)	Read the 'ESM-4 Create Dialogue Maps' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. # Create Dialogue Maps (Screen Flows) ## Objective Visualize screen-to-screen flows and entity relationships using Draw.io diagrams. ## Artifacts Created - `docs/ux/2_dialogue-maps/screen-flow.drawio` - Visual flow diagrams ## Process ### 1. Create Domain Model Diagram - Map core entities (Playbook, Workflow, Phase, Activity, Artifact, Role, Howto) - Show relationships between entities - Document cardinality and dependencies - Use color coding: - Blue (#4682B4): FOB screens - Green (#82b366): Homebase screens - Purple (#9673a6): MCP operations ### 2. Create MVP Flow Diagram - Create horizontal swimlanes per Act (ACT 0 → ACT 9) - Add screen boxes with Screen IDs (e.g., `FOB-PLAYBOOKS-LIST+FIND-1`) - Bold border for LIST+FIND entry points - Add navigation arrows showing screen-to-screen flow - Bold black arrows for main progression flow - Document screen states (loading, error, success) ### 3. Validate Diagram Visually - Human eye check: Does it look clear and understandable? - Fresh eyes test: Can someone unfamiliar understand immediately? - Arrow clarity test: Can you trace each flow path without confusion? - Primary user path is visually prominent and easy to follow ## Tools - Draw.io for diagram creation - Use tabs: "Domain Model" and "MVP Flow - Local FOB" ## Deliverables - ✅ Domain model diagram - ✅ Complete MVP flow with all Acts - ✅ Each screen box labeled with Screen ID: `FOB-{ENTITY}-{OPERATION}-{VERSION}` - ✅ LIST+FIND screens have bold borders (entry points) - ✅ Screen IDs match User Journey exactly - ✅ Navigation arrows show screen-to-screen flow - ✅ Grep-able: Can find screen in diagram by ID - ✅ Screen state documentation - ✅ Navigation flow clarity ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - User Journey (Document, Required) — produced by Define User Journey (#36). - IA Guidelines (Document, Required) — produced by Define Information Architecture (#37).
Write Feature Files	ESM-5	Envision the System	Junior Edda	Inception (#1)	Read the 'ESM-5 Write Feature Files' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. APPEND TO GUIDANCE: --- ## Feature file location (layout) Write `.feature` files to `docs/features/act-/`. That tree is the living BDD specification. After TFK-02 is in place, the same tree is also the AT runner path (`behave.ini` `paths = docs/features`) — there is no separate promote/copy into `tests/acceptance/` or `features/at/`. Tag not-yet-implemented scenarios `@wip` so CI can exclude them (`tags = ~@wip`) once behave is configured. --- ## TFK Integration: Step Library Consumption (optional, when TFK exists) ESM does not depend on TFK.* Workflow order is ESM → … → TFK. On a greenfield first pass, write clear, unconstrained Gherkin that expresses user goals. Do not block ESM-05 waiting for Step/Fixture Library Catalogs. When TFK already exists (bootstrap repos, later iterations, or after TFK-03/04 have run): 1. Prefer catalog phrases: Open the Step Library Catalog (TFK-03) and reuse existing step patterns (navigation, forms, tables, auth, assertions, dialogs). 2. Assemble from library: Compose scenarios from catalog building blocks so they become immediately executable once AT steps exist. 3. If a phrase is missing: Do not invent one-off step wording that will never be implemented. Either (a) write natural Gherkin and note a follow-up TFK-07 to add the phrase, or (b) if TFK-07 is available in this iteration, invoke it to extend the catalog. 4. Fixtures: Same rule for Fixture Library Catalog (TFK-04) — optional when present; otherwise describe data needs in scenario prose / examples tables. ### Why this split matters - Specification first (ESM): feature files are requirements, not a hostage of the test harness. - Automation second (TFK): TFK binds phrases to Django-client (AT) and Playwright (E2E) implementations. - No circular dependency: ESM-05 never lists TFK-03/04 artifacts as required inputs. ## Inputs (additional) - Step Library Catalog (Document, Optional) — produced by TFK-03 Build Step Library; use when available. - Fixture Library Catalog (Document, Optional) — produced by TFK-04 Build Fixture Library; use when available. --- ## Feature file location (layout) Write `.feature` files to `docs/features/act-/`. That tree is the living BDD specification. After TFK-02 is in place, the same tree is also the AT runner path (`behave.ini` `paths = docs/features`) — there is no separate promote/copy into `tests/acceptance/` or `features/at/`. Tag not-yet-implemented scenarios `@wip` so CI can exclude them (`tags = ~@wip`) once behave is configured. --- ## TFK Integration: Step Library Consumption (optional, when TFK exists) ESM does not depend on TFK.* Workflow order is ESM → … → TFK. On a greenfield first pass, write clear, unconstrained Gherkin that expresses user goals. Do not block ESM-05 waiting for Step/Fixture Library Catalogs. When TFK already exists (bootstrap repos, later iterations, or after TFK-03/04 have run): 1. Prefer catalog phrases: Open the Step Library Catalog (TFK-03) and reuse existing step patterns (navigation, forms, tables, auth, assertions, dialogs). 2. Assemble from library: Compose scenarios from catalog building blocks so they become immediately executable once AT steps exist. 3. If a phrase is missing: Do not invent one-off step wording that will never be implemented. Either (a) write natural Gherkin and note a follow-up TFK-07 to add the phrase, or (b) if TFK-07 is available in this iteration, invoke it to extend the catalog. 4. Fixtures: Same rule for Fixture Library Catalog (TFK-04) — optional when present; otherwise describe data needs in scenario prose / examples tables. ### Why this split matters - Specification first (ESM): feature files are requirements, not a hostage of the test harness. - Automation second (TFK): TFK binds phrases to Django-client (AT) and Playwright (E2E) implementations. - No circular dependency: ESM-05 never lists TFK-03/04 artifacts as required inputs. ## Inputs (additional) - Step Library Catalog (Document, Optional) — produced by TFK-03 Build Step Library; use when available. - Fixture Library Catalog (Document, Optional) — produced by TFK-04 Build Fixture Library; use when available. --- ## Responsive Acceptance Scenarios Read the Responsive Coverage Contract and Screen ID-to-recipe coverage table in `docs/ux/IA_guidelines.md` before writing scenarios. - Shared page-layout recipes carry the default behavior; do not duplicate identical viewport scenarios in every feature file. - When a screen departs from its recipe, add focused Gherkin scenarios for each affected target viewport or viewport class. - Express observable outcomes: stacking order, action reachability, navigation collapse, intentional component overflow, full-viewport behavior, and absence of clipping, overlap, or unintended page-level horizontal scrolling. - Use exact CSS viewport dimensions from the IA matrix in Examples tables when size matters. Do not use only vague labels such as mobile, tablet, or desktop. - Keep the Screen ID, recipe name, affected viewport profile, and expected behavior traceable in the scenario or accompanying Examples table. ESM-05 specifies behavior. Pixel-perfect comparison and screenshot evidence belong to ESM-06 and BPE-05.
Create Mockups	ESM-6	Envision the System	Junior Edda	Inception (#1)	Read the 'ESM-6 Create Mockups' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. # Create Mockups (Prototyped Screens) ## Objective Build functional prototypes with representative mock data to validate UX before full implementation. Mockups are design reference — not connected to live data or production runtime. ## Layout Mockups live in a dedicated `mockups/` package at the repo root, separate from production apps. ``` mockups/ urls.py # URL patterns for all mockup screens (canonical inventory) views.py # views with hardcoded fixture data templates/mockups/ base.html # shared shell — banner and screen inventory ``` The package is included from the project URLconf. It is not a production feature surface. ## Gating — DEBUG only Mockup routes are mounted only when `settings.DEBUG` is true. In test and production they are not mounted and return 404. ```python if settings.DEBUG: urlpatterns.append(path("mockups/", include("mockups.urls"))) ``` `runserver` with development settings (`DEBUG=True`) serves them at `/mockups/`. Pytest and production settings (`DEBUG=False`) do not. ## Mockup chrome (required on every screen) Every mockup inherits a single shared shell. Do not duplicate mockup chrome inside individual screens. Two signals are always present (except the full-bleed exception below): ### 1. Persistent mockup banner A fixed banner at the top of the viewport states that the screen is design reference only and is not connected to live data. - Defined once in the shared shell. - Never removed or hidden on individual mockup screens. - Production chrome (nav, page header) sits below it. ### 2. Shared screen inventory A single footer (or equivalent persistent index) lists every registered mockup screen. This is the canonical cross-link index for designers, reviewers, and agents jumping between prototypes. Rules: \| Rule \| Detail \| \|---\|---\| \| Single source \| Maintain inventory links in the shared shell only — never add a second per-page inventory block. \| \| Keep in sync \| When you add a mockup screen, add its inventory link in the same change. \| \| Page-specific hints \| Optional suffix text (reset notes, store keys, and similar) attaches to the shared inventory. Do not fork the inventory. \| \| Test hook \| The inventory root has a stable test id so agents and AT can find it. \| Representative detail/edit screens that are reachable from list rows do not need inventory links unless they are primary entry points. Full-bleed exception: A screen whose layout needs the full viewport height may hide the inventory. The banner stays visible. ## Process ### 1. Register every screen Every prototype in the Screen Flow is a registered mockup under `mockups/urls.py`, served at `/mockups/`. The inventory in the shared shell is the canonical list — keep it in lockstep with registrations. ### 2. Use representative mock data Mock data is hardcoded fixtures. Mockup screens have no live datastore access and no production auth checks. Cover the states the IA requires: loading, empty, error, success. ### 3. Build screens from the shared shell Each screen extends the shared mockup shell (inherits banner + inventory). - Follow the IA Guidelines for layout, page headers, components, and test-id naming. - Visible title and subtitle use production copy — no Screen IDs and no “mockup” or storage jargon in the page header. - Screen traceability lives in metadata (screen-id slot → comment in the shell; test ids on containers and controls). - Mockup signaling is only the banner and the shared inventory. Interactive prototypes may append reset hints on the inventory, never in the page header. - Represent UI states; use semantic HTML, ARIA labels, and keyboard navigation. ### 4. Accessibility - Semantic structure (`nav`, `main`, `section`) - ARIA labels and roles on interactive elements - Keyboard navigation - Focus management for modals and alerts ## Deliverables - ✅ Shared mockup shell with persistent banner and single screen inventory - ✅ Every Screen Flow prototype registered and linked from that inventory (no per-page duplicate inventories) - ✅ Representative mock data; no live datastore; no production auth - ✅ Production-real page headers; Screen IDs only in metadata / test ids - ✅ All required UI states (empty, loaded, error, success) - ✅ Accessibility (ARIA, semantic HTML, keyboard nav) - ✅ Mockups accessible at `/mockups/` when `DEBUG=True`; not mounted and 404 otherwise ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - User Journey (Document, Required) — produced by Define User Journey (#36). - IA Guidelines (Document, Required) — produced by Define Information Architecture (#37). - Screen Flow / Dialogue Map (Diagram, Required) — produced by Create Dialogue Maps (#38). --- ## Responsive Visual Validation The Responsive Coverage Contract in `docs/ux/IA_guidelines.md` is authoritative. Render and visually inspect every registered mockup at every required target viewport. Use the same CSS-pixel profile names and dimensions defined by the IA. A single responsive mockup may satisfy multiple profiles; separate mockup implementations are not required. For each Screen ID and viewport, verify: - page shell, navigation, breadcrumbs, title, metadata, and action clusters follow the mapped recipe; - columns stack in the documented order and reading/focus order stays coherent; - text, controls, menus, tooltips, modals, feedback, tables, rails, canvases, and split panes do not clip or overlap; - no unintended page-level horizontal scrollbar appears; intentional table/component overflow remains local; - primary navigation and primary actions remain reachable; - low-height profiles preserve deliberate scrolling or the documented full-viewport fit; - content remains readable without browser zoom and interactive targets remain usable by touch and keyboard. Record a responsive evidence index containing Screen ID, recipe, viewport profile, result, screenshot/reference, reviewer, and any approved exception. Fix failures before completing ESM-06. An exception is valid only when it is documented in the IA and represented by a focused feature scenario.
Feed into Implementation	ESM-7	Envision the System	Junior Edda	Inception (#1)	Read the 'ESM-7 Feed into Implementation' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. # Feed into Feature Implementation Workflow ## Objective Transition from UX design to full backend implementation. ## Process ### 1. Handoff Checklist Ensure all UX artifacts are complete before implementation: Activity 1 → Activity 2: - [ ] Screen ID convention understood - [ ] Traceability requirements clear - [ ] Important guidelines reviewed Activity 2 → Activity 3: - [ ] User journey documented - [ ] All Acts defined with personas - [ ] Screen IDs assigned to all screens Activity 3 → Activity 4: - [ ] IA guidelines documented - [ ] Design system tokens defined - [ ] Navigation structure clear Activity 4 → Activity 5: - [ ] Domain model diagram complete - [ ] MVP flow diagram shows all screens - [ ] Screen states documented - [ ] Flow validated visually (human eye check) Activity 5 → Activity 6: - [ ] All CRUDLF feature files written - [ ] Scenarios follow BDD best practices - [ ] Navbar integration scenarios added - [ ] Error/edge cases covered Activity 6 → Activity 7: - [ ] All mockup templates created - [ ] Mock views functional - [ ] All UI states represented - [ ] Accessibility attributes present - [ ] `data-testid` attributes added - [ ] Design system compliance verified Activity 7 — UX complete: - [ ] All UX artifacts complete (Activities 1-6) - [ ] Feature files ready for implementation - [ ] Mockups ready for conversion to real views - [ ] Screen IDs documented across all artifacts ### 2. Traceability Verification Verify Screen ID appears in all 5 artifacts: 1. ✅ User Journey (section header) 2. ✅ Screen Flow Diagram (box label) 3. ✅ Feature File (feature title) 4. ✅ Template (HTML comment + hidden div) 5. ✅ Tests (test names + docstrings) Grep Test: `grep -r "FOB-{ENTITY}-{OPERATION}-{VERSION}" .` ## Deliverables - ✅ All UX artifacts complete (Activities 1-6) - ✅ Feature files ready for implementation - ✅ Mockups ready for implementation - ✅ Screen ID traceability complete - ✅ Handoff checklist verified ## Next Steps: Remaining Elaboration before Construction ESM is the first Inception workflow. Three more workflows must complete before building starts: \| Gate \| Artifact \| Workflow if missing \| \|------\|----------\|---------------------\| \| DTA \| `docs/architecture/SAO.md` \| DTA — Define Architecture \| \| DSP \| `CLAUDE.md` \| DSP — Deploy Software Process \| \| BSP \| `Makefile` + `requirements.txt` \| BSP — Bootstrap Project \| Run DTA next. DSP follows DTA (needs SAO.md). BSP follows DSP. When all four gates pass, see BSP-08 for the Construction Handoff and mode selection.
Analyze ESM Artifacts	DTA-1	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-1 Analyze ESM Artifacts' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Analyze ESM Artifacts ## Objective Extract capability requirements per architectural domain from the ESM output artifacts (user journey, screen flows, .feature files, IA guidelines). This structured requirements list feeds all subsequent DTA activities (DTA-02 through DTA-17, and Activities 200/201). --- ## Process ### 1. Read User Journey - Extract domain entities (e.g., User, Playbook, Workflow, Activity, Skill) - Identify interaction patterns (CRUD, search, import/export, real-time updates) - Note personas and roles that imply auth/authorization requirements - Flag integration points (external systems, APIs, data sources) ### 2. Read Screen Flows - Identify UI complexity per screen type: - Simple: static content, read-only views - Moderate: forms, tables, filters, pagination - Complex: graphs, drag-and-drop, real-time, rich text editors - Count screen types to estimate frontend effort - Note navigation patterns (breadcrumbs, tabs, modals, wizards) ### 3. Read Feature Files (.feature) - Extract required capabilities from scenario steps: - CRUD operations per entity - Search and filter requirements - Authentication and authorization scenarios - Error handling and edge cases - Data validation rules - Map scenarios to capability domains (GUI_FORM, API_CRUD, AUTH_SESSION, etc.) ### 4. Read IA Guidelines - Extract design system requirements (component library, theming) - Note accessibility requirements (ARIA, keyboard navigation) - Identify responsive/multi-device needs ### 5. Compile Requirements per Domain Produce a structured list mapping ESM findings to the 16 core architectural domains plus the 2 optional ones (AI Agent Architecture, MCP Architecture): ``` Domain: Application Blocks (DTA-02) - 5 bounded contexts identified: Auth, Methodology, Planning, MCP, Web UI - Dependency: Methodology → Planning (planning reads methodology) Domain: Integration & API Design (DTA-03) - MCP stdio interface required (read-only) - Web UI HTTP interface required (full CRUD) - No external 3rd party integrations identified Domain: Code Organization (DTA-04) - Monorepo structure implied (single Django project) - 3 layers visible: models, services, views Domain: Data Architecture (DTA-05) - 6 entities with relationships (graph-like) - Version tracking required - Import/export functionality needed ... (continue for all 16 domains, plus AI Agent Architecture and MCP Architecture if applicable) ``` This structured requirements document is the single shared input every domain activity below reads. Nothing in Step 6 depends on any domain activity's own decision — that's what makes the fan-out below safe. ### 6. Dispatch Domain Decision Workers (parallel) Apply rule `do-fan-out-independent-work`. The item list is every remaining DTA domain activity: Activities 43 through 58 (Application Blocks through Documentation Strategy), plus Activity 201 (Define MCP Architecture) and Activity 200 (Define AI Agent Architecture) when applicable to this project. - Footprint, per item: reads only the Step 5 requirements document (and scans Playbook Skills, as each domain activity's own guidance already directs). Writes only its own decision block for inclusion in SAO.md. No domain activity's guidance references another domain's decision — confirmed by direct reading of Application Blocks (43), Infrastructure (50), CI/CD Pipeline (51), and Security (55) — so the conflict map here is empty by construction: dispatch all of them in one wave. - Do not wait for one domain activity to finish before starting the next. There is no ordering requirement between them. - Convergence: Activity 59 (Write SAO.md) is the single convergence point. It now includes an explicit cross-domain consistency check (see that activity's own guidance) — do not treat any individual domain worker's output as final until that check has run, since a domain decision made in isolation (e.g. a compute model choice) can constrain a decision another worker made independently (e.g. a CI/CD deploy target, or a blue/green mechanism). - Collect every domain worker's decision block and skill-coverage report before proceeding to Activity 59. --- ## Deliverables - ✅ Domain entities extracted from user journey - ✅ UI complexity assessed from screen flows - ✅ Capability domains mapped from .feature files - ✅ Structured requirements list produced for all 16 core architectural domains (and AI Agent / MCP Architecture, if applicable) - ✅ Domain decision workers dispatched in parallel for Activities 43-58 and, if applicable, 200/201 - ✅ Ready to proceed to Activity 59 (Write SAO.md) once all domain workers report back ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - User Journey (Document, Required) — produced by Define User Journey (#36). - IA Guidelines (Document, Required) — produced by Define Information Architecture (#37).
Define Application Blocks	DTA-2	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-2 Define Application Blocks' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Application Blocks ## Objective Identify bounded contexts, domain packages, module boundaries, and dependency rules. Choose the foundational architectural pattern (MVC, event-driven, modular monolith, microservices, etc.). --- ## Internal Process Every domain activity follows this structure: 1. Identify needs — what does ESM require for this domain? 2. Scan Skills — query Playbook Skills by `capability_domain` for this domain 3. Propose options — 2-3 approaches with Skill coverage, cost, risk 4. Record decision — user picks, rationale documented --- ## Decisions to Make ### 1. Bounded Contexts / Domain Packages - Review ESM entities and their relationships - Group entities into cohesive domain packages - Define which entities belong together (high cohesion) vs. which are separate concerns (loose coupling) - Example groupings: - `auth/` — User, Session, Permissions - `methodology/` — Playbook, Workflow, Activity, Skill - `planning/` — WorkPlan, Task, Estimation - `mcp/` — MCP protocol, tools, stdio interface ### 2. Module Boundaries & Dependency Rules - Define what can import what (dependency direction) - Identify shared kernel vs. independent modules - Example rules: - `planning` → depends on `methodology` (reads playbook structure) - `mcp` → depends on `methodology` (exposes methodology as tools) - `auth` → independent (no methodology dependency) - No circular dependencies allowed ### 3. Foundational Architectural Pattern Choose one: - MVC / MTV — Model-Template-View (Django default). Best for: server-rendered web apps with moderate complexity. - Event-Driven — Publish/subscribe, event sourcing. Best for: highly decoupled systems, real-time requirements. - Modular Monolith — Single deployable unit with strict module boundaries. Best for: starting simple with clear growth path. - Microservices — Independent deployable services. Best for: large teams, independent scaling needs. - Batch Processing — Scheduled jobs processing data in bulk. Best for: data pipelines, ETL. - Hybrid — Combine patterns (e.g., MVC for web + event-driven for async). ### 3a. UI Architecture Patterns (if system has a web/desktop UI) Define the presentation layer architecture: Rendering model: - Server-rendered — HTML generated on server (Django templates, Jinja2). Best for: testability, SEO, minimal JS. - SPA — Single Page Application (React, Vue, Svelte). Best for: rich interactivity, complex state. - Hybrid — Server-rendered with progressive enhancement (HTMX, Alpine.js, Turbo). Best for: server-side simplicity with dynamic UX. Layout pattern: - Single-panel — One main content area. Best for: simple CRUD, mobile-first. - Multi-panel — Split layout (navigation + content + detail). Best for: explorer-style UIs, dashboards. - Wizard/stepper — Sequential steps. Best for: complex forms, onboarding. Component interaction model: - Full page reload — Traditional links/forms. Simplest, most testable. - Partial updates — Server returns HTML fragments, client swaps them (HTMX, Turbo Frames). Testable with standard server-side tests. - Client-side state — JS manages state, talks to API (React+Redux, Vue+Pinia). Requires browser-based testing. Visualization approach (if applicable): - Server-generated — Graphviz, matplotlib, SVG generation on server. Best for: static/semi-static diagrams. - Client-rendered — D3.js, Cytoscape.js, Chart.js. Best for: interactive, real-time visualizations. - Hybrid — Server generates data, client renders. Best for: large datasets with interactive exploration. Document rationale for each choice, especially impact on testability and build complexity. ### 4. Scan Skills & Reference Implementations Query Playbook Skills where `capability_domain` in: - `APP_STRUCTURE` - `DOMAIN_MODELING` - `DEPENDENCY_INJECTION` Report coverage: ``` Skill Coverage for Application Blocks: APP_STRUCTURE \| [Django App Architecture Skill] ✅ \| Reference: Repository pattern, service layers, dependency rules \| Example: Mimir methodology/ app structure DOMAIN_MODELING \| [DDD Bounded Contexts Skill] ✅ \| Reference: Entity modeling, aggregate boundaries \| Example: Playbook → Workflow → Activity hierarchy DEPENDENCY_INJECTION \| ❌ No Skill - will create custom patterns \| Estimated impact: +1 iteration for pattern definition ``` If reference implementations exist: "Following Django app patterns from [Django App Architecture Skill](#skill-456), recommend service layer approach with estimated 2-day implementation." If gaps exist: "No Skill for Dependency Injection — will need to define patterns. Estimated impact: +1 iteration." --- ## Deliverables - ✅ Bounded contexts / domain packages identified and documented - ✅ Module dependency rules defined (what imports what) - ✅ Foundational pattern chosen with rationale - ✅ UI architecture patterns defined (if applicable): rendering model, layout, interaction model, visualization - ✅ Skill coverage assessed for this domain with reference implementations - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Integration & API Design	DTA-3	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-3 Define Integration & API Design' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Integration & API Design ## Objective Choose API style, versioning strategy, contract approach, external integration patterns, and inter-service communication model. --- ## Decisions to Make ### 1. API Style Choose one or hybrid: - REST — Resource-oriented, HTTP verbs, JSON. Best for: standard CRUD web apps. - GraphQL — Query language, single endpoint. Best for: complex data fetching, mobile clients. - gRPC — Binary protocol, protobuf. Best for: internal service-to-service, high throughput. - MCP (Model Context Protocol) — stdio-based, tool-oriented. Best for: AI agent integration. - Hybrid — e.g., REST for web UI + MCP for AI agents. ### 2. API Versioning Strategy Choose one: - URL path — `/api/v1/playbooks/` → simple, visible, easy to route - Header — `Accept: application/vnd.mimir.v1+json` → clean URLs - Query param — `/api/playbooks/?version=1` → easy to test - No versioning — acceptable for internal-only APIs in early stages ### 3. Contract Approach Choose one: - Contract-first — Write OpenAPI/AsyncAPI spec first, generate code from it - Code-first — Write code first, generate spec from annotations/decorators - No formal contract — acceptable for internal APIs with single consumer ### 4. External Integrations - Identify 3rd party APIs the system consumes (if any) - Define webhook patterns (inbound/outbound) - Define event bus usage (if applicable) - Define retry and error handling for external calls ### 5. Inter-Service Communication If multiple services/processes exist: - Sync (HTTP/gRPC) — Request-response. Simple but creates coupling. - Async (Message Queue) — Fire-and-forget. Decoupled but complex. - Shared Database — Both processes read/write same DB. Simple but limits scaling. - File-based — Export/import via files. Simple for batch scenarios. ### 6. Implementation Patterns (document during/after implementation) For each chosen API style, document recurring implementation patterns as they emerge: - Service-to-transport mapping — How business logic maps to API endpoints/tools. Example: thin controller/tool wrapping a service method. - Sync/async boundary — If the API layer is async but business logic is sync (or vice versa), document the bridging pattern and any pitfalls discovered. - Protocol-specific constraints — Transport-layer constraints that affect architecture. Examples: stdio pollution in MCP, CORS in REST, N+1 in GraphQL. - Shared service layer — If multiple transports (e.g., web UI + API + MCP) share business logic, document how the service layer is structured to serve all consumers. - Error propagation — How errors from the service layer translate to API responses per transport (HTTP status codes, MCP error objects, gRPC status codes). > Note: This subsection starts as placeholder during DTA. Populate it during implementation and feed findings back into SAO.md via the "Discovered Patterns" section (DTA-18). ### 7. Scan Skills Query Playbook Skills where `capability_domain` in: - `API_REST` - `API_GRAPHQL` - `API_GRPC` - `API_CONTRACT` Report coverage and gaps. --- ## Deliverables - ✅ API style chosen with rationale - ✅ Versioning strategy defined - ✅ Contract approach selected - ✅ External integrations identified and patterns defined - ✅ Inter-service communication model chosen (if applicable) - ✅ Implementation patterns placeholder created (populated during/after implementation) - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Code Organization	DTA-4	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-4 Define Code Organization' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Code Organization ## Objective Define project layout, layer separation, naming conventions, and shared library approach. This translates the logical application blocks (DTA-02) into a physical directory and file structure. --- ## Decisions to Make ### 1. Repository Strategy Choose one: - Monorepo — Single repository, all code together. Best for: small teams, shared tooling. - Polyrepo — Separate repos per service/component. Best for: independent teams, different release cycles. - Monorepo with packages — Single repo with npm/pip workspaces. Best for: shared code with clear boundaries. ### 2. Directory Structure & Layer Separation Define the top-level project layout: - Where do models live? - Where do services (business logic) live? - Where do views/controllers live? - Where do templates/frontend assets live? - Where do tests live? - Where do docs live? Example (Django): ``` project/ ├── app_name/ │ ├── models/ # Data layer │ ├── services/ # Business logic │ ├── views/ # HTTP interface (Django views) │ └── templates/ # HTML templates ├── mcp/ # MCP interface ├── tests/ # All tests ├── docs/ # Documentation └── manage.py ``` ### 3. Naming Conventions Define rules for: - Files: snake_case.py, kebab-case.html, PascalCase.tsx - Classes: PascalCase - Functions/methods: snake_case - URLs: kebab-case (`/playbooks/playbook/list/`) - Database tables: snake_case (auto from models) - Constants: UPPER_SNAKE_CASE ### 4. Shared Libraries / Common Utilities - Where do cross-cutting concerns live? (logging, error handling, decorators) - How are shared types/interfaces defined? - Import rules: what can import from `common/`? ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `CODE_ORG` - `PROJECT_LAYOUT` Report coverage and gaps. --- ## Deliverables - ✅ Repository strategy chosen - ✅ Directory structure defined with layer separation - ✅ Naming conventions documented - ✅ Shared library approach defined - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Data Architecture	DTA-5	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-5 Define Data Architecture' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Data Architecture ## Objective Choose database engine, define schema strategy, select data access patterns, and plan migration and caching approaches. --- ## Decisions to Make ### 1. Database Engine Choose one (or combination): - SQLite — File-based, zero config. Best for: desktop apps, prototypes, single-user. - PostgreSQL — Full-featured relational. Best for: production web apps, complex queries. - MySQL/MariaDB — Relational, widely supported. Best for: standard web apps. - Neo4j — Graph database. Best for: relationship-heavy data, graph traversals. - MongoDB — Document store. Best for: flexible schemas, rapid prototyping. - Combination — e.g., SQLite for FOB + Neo4j for HOMEBASE. Document rationale: performance needs, data model fit, team expertise, licensing. ### 2. Schema Strategy - Migration tool: Django migrations, Alembic, Flyway, manual SQL - Versioning: How are schema changes tracked? Numbered migrations? Timestamps? - Seed data: How is initial/test data loaded? Fixtures, factories, management commands? - Schema evolution: How are breaking changes handled? Expand-contract pattern? ### 3. Data Access Patterns Choose one: - ORM — Object-Relational Mapping (Django ORM, SQLAlchemy). Best for: standard CRUD. - Repository Pattern — Abstract interface over storage. Best for: storage-agnostic design, testability. - Raw Queries — Direct SQL/Cypher. Best for: complex queries, performance-critical paths. - Hybrid — ORM for simple CRUD + raw queries for complex operations. ### 4. Read/Write Separation & Caching - Is read/write separation needed? (CQRS pattern) - Cache strategy: application-level cache, query cache, HTTP cache - Cache invalidation approach - Connection pooling configuration ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `DB_RELATIONAL` - `DB_GRAPH` - `DATA_ACCESS` Report coverage and gaps. --- ## Deliverables - ✅ Database engine chosen with rationale - ✅ Schema strategy defined (migrations, versioning, seed data) - ✅ Data access pattern selected - ✅ Caching strategy defined (if applicable) - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Test Strategy	DTA-6	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-6 Define Test Strategy' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Test Strategy ## Objective Define the test approach (prefer Test Trophy over Pyramid when integration-heavy), choose frameworks per layer, establish coverage targets, plan test data management, and configure CI integration for tests. Seed only: Record motivators, layer weights, and framework choices for inclusion in `docs/architecture/SAO.md` § Test Strategy via DTA-18. Do not finalize AT/E2E directory layout or step-library paths here — TFK-01 fleshes those details into the same SAO section before BPE. --- ## Decisions to Make ### 1. Trophy / Pyramid & Coverage Targets Define ratio and targets per level: - Unit tests — Isolated logic, services, utilities. Target: thin / focused coverage. - Integration tests — Views, DB queries, service interactions. Target: all CRUD paths (main bet when using Trophy). - Acceptance (AT) — BDD `.feature` scenarios; executable requirements. - E2E tests — Full user journeys via browser. Target: critical paths only. - Contract tests — API contract validation (if applicable). Define what "100% pass rate" means (all non-`@wip` tests must pass before declaring feature complete). ### 2. Frameworks per Layer Choose frameworks for each test level: - Unit: pytest, unittest, Jest, Vitest - Integration: pytest + Django test client, supertest - AT: behave-django (Django test client in steps) - E2E: Playwright, Cypress, Selenium - Contract: Pact, Schemathesis - Performance: Locust, k6, Artillery ### 3. Test Data Management - Fixtures: Static JSON/YAML fixtures loaded before tests - Factories: Dynamic data generation (factory_boy, Faker) - DB seeding: Management commands for consistent test state - Isolation: How are tests isolated? Transaction rollback? Fresh DB? - Makefile targets: `make test`, `make test-unit`, `make test-at`, `make test-e2e` ### 4. CI Integration - When do tests run? On every push? On PR? Nightly? - Failure gates: Which test failures block merge/deploy? - Test reporting: Where are results published? - Flaky test policy: How are flaky tests handled? ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `TEST_UNIT` - `TEST_INTEGRATION` - `TEST_E2E` Report coverage and gaps. ### 6. Agent test lanes (when SAO §17 applies) When the project has in-app LLM agents (SAO §17 is not "Not applicable"), seed four agent test lanes in the Test Strategy section for TFK-01 to flesh out before BPE: \| Lane \| Name \| CI gate \| Assert \| \|------\|------\|---------\|--------\| \| 1 \| Control-plane proofs \| PR when `AGENTS_ENABLED=true` \| PRF-* rows + CAP-004 ScriptedLLM + run trace (`assert_agent_story`) \| \| 2 \| Deterministic shell \| PR (normal integration) \| D0 pre-filter, JSON parse, validate-before-LLM — no LLM mock \| \| 3 \| Live contract eval \| Nightly / optional CD \| temp=0, schema/contract bounds only — not PR merge gate \| \| 4 \| Task performance quality \| Promotion band \| TASK-* golden oracle vs structured ground truth \| Seed only here: record that lanes 1–2 belong in default PR quality gates when agents are enabled; lanes 3–4 use separate `agent-eval.yml` (workflow_dispatch + schedule) and do not block merge. Do not finalize PRF test file paths, `tests/support/agent_story.py`, `tests/fixtures/llm_scripts/`, Makefile targets (`test-agent-proof`, `test-agent-quality`), or pytest markers here — TFK-01 fleshes lane wiring, directory layout, and CI/Makefile integration into SAO § Test Strategy before BPE. --- ## Deliverables - ✅ Test approach (Trophy/Pyramid) defined with coverage targets - ✅ Frameworks chosen per test level - ✅ Test data management approach defined - ✅ CI integration rules established - ✅ Skill coverage assessed for this domain - ✅ Seed decision recorded for SAO.md § Test Strategy (DTA-18); TFK-01 will flesh the section before BPE - ✅ Agent test lanes seeded (when SAO §17 applies); TFK-01 will flesh lane details before BPE
Define Performance & Scalability	DTA-7	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-7 Define Performance & Scalability' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Performance & Scalability ## Objective Define expected load profile, caching tiers, async processing strategy, connection pooling, scaling approach, and capacity planning. --- ## Decisions to Make ### 1. Expected Load Profile Characterize the system's expected usage: - Concurrent users: How many at peak? - Requests/sec: Expected throughput per endpoint category - Data volume: How much data at launch? At 1 year? At 5 years? - Read/write ratio: What percentage of requests are reads vs writes? - Burst patterns: Are there predictable spikes (daily, weekly, seasonal)? ### 2. Caching Tiers Define caching at each level: - Application cache: In-memory cache (Django cache framework, Redis) - CDN: Static assets, pre-rendered pages - DB query cache: Query result caching, materialized views - Session cache: Session storage (DB, Redis, cookie-based) - HTTP cache: Cache-Control headers, ETags, conditional requests For each tier: what to cache, TTL, invalidation strategy. ### 3. Async Processing - Task queues: Celery, RQ, Dramatiq — for background jobs - Workers: How many? Auto-scaling? - Use cases: Email sending, PDF generation, data import/export, AI inference - Priority queues: Critical vs. best-effort tasks ### 4. Connection Pooling - DB connections: Pool size, timeout, max overflow - HTTP clients: Connection reuse for external API calls - WebSocket connections (if applicable) ### 5. Scaling Strategy - Horizontal: Add more instances behind load balancer - Vertical: Increase instance resources (CPU, RAM) - Auto-scaling: Triggers (CPU%, request count, queue depth) - Database scaling: Read replicas, sharding, connection pooling ### 6. Capacity Planning - Baseline resource requirements - Growth projections (linear, exponential) - Cost model per scaling tier - When to re-evaluate architecture ### 7. Scan Skills Query Playbook Skills where `capability_domain` in: - `PERF_CACHING` - `PERF_ASYNC` - `PERF_SCALING` Report coverage and gaps. --- ## Deliverables - ✅ Load profile characterized - ✅ Caching strategy defined per tier - ✅ Async processing approach chosen - ✅ Connection pooling configured - ✅ Scaling strategy defined - ✅ Capacity plan with cost model - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Error Handling & Resilience	DTA-8	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-8 Define Error Handling & Resilience' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Error Handling & Resilience ## Objective Define error taxonomy, error response format, retry policies, circuit breaker patterns, graceful degradation strategy, and idempotency requirements. --- ## Decisions to Make ### 1. Error Taxonomy Classify errors into categories: - Domain errors — Business rule violations (e.g., "Cannot delete released playbook") - Validation errors — Input validation failures (e.g., "Name is required") - Infrastructure errors — DB connection lost, disk full, OOM - External service errors — 3rd party API timeout, rate limit exceeded - Authentication/Authorization errors — Invalid session, insufficient permissions For each category: how is it logged, how is it presented to the user, what's the HTTP status code? ### 2. Error Response Format Define a standard error envelope: ```json { "error": { "code": "PLAYBOOK_NOT_FOUND", "message": "Playbook with ID abc-123 does not exist", "details": {}, "request_id": "req-xyz-789" } } ``` Decide: - Standard error codes (enum or free-text?) - User-facing messages (localization needed?) - Technical details (shown in dev, hidden in prod?) - Correlation/request IDs for tracing ### 3. Retry Policies For each type of retriable operation: - Which operations are retriable? (network calls, DB transactions, queue publish) - Backoff strategy: linear, exponential, jitter - Max attempts before giving up - Dead letter queue for permanently failed operations ### 4. Circuit Breakers For external service dependencies: - Failure threshold before circuit opens (e.g., 5 failures in 30 seconds) - Fallback behavior when circuit is open - Half-open recovery: how and when to retry - Monitoring: how to alert on open circuits ### 5. Graceful Degradation - Which features can operate in degraded mode? - How are users notified of degraded functionality? - Fallback data sources (cached data, default values) - Feature flags for emergency feature disabling ### 6. Idempotency - Which write operations must be idempotent? (payment processing, data import) - How is idempotency ensured? (idempotency keys, upsert patterns, deduplication) - Timeout handling: what happens if a request times out but the operation completed? ### 7. Scan Skills Query Playbook Skills where `capability_domain` in: - `ERR_HANDLING` - `ERR_RESILIENCE` - `ERR_RETRY` Report coverage and gaps. --- ## Deliverables - ✅ Error taxonomy defined with handling rules per category - ✅ Error response format standardized - ✅ Retry policies defined for retriable operations - ✅ Circuit breaker patterns defined (if applicable) - ✅ Graceful degradation strategy documented - ✅ Idempotency requirements identified - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Infrastructure	DTA-9	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-9 Define Infrastructure' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Infrastructure ## Objective Define the local development environment, cloud provider and compute model, networking setup, and Infrastructure as Code tooling. --- ## Decisions to Make ### 1. Local Development Environment - Containerization: Docker, Podman, or native? - Dev/prod parity: How close is local to production? - Makefile targets: `make provision` (install all deps), `make run` (start everything) - Required tools: Which CLI tools, SDKs, runtimes must be installed? - Environment variables: How are they managed locally? (.env file, direnv) ### 2. Cloud Provider & Compute Model Choose compute model: - Kubernetes (EKS/GKE/AKS) — Container orchestration. Best for: complex deployments, auto-scaling. - Container service (ECS/Cloud Run) — Managed containers. Best for: simpler container deployments. - Serverless (Lambda/Cloud Functions) — Event-driven functions. Best for: sporadic workloads. - VMs (EC2/Compute Engine) — Traditional. Best for: legacy apps, specific OS needs. - PaaS (Heroku/Railway/Render) — Managed platform. Best for: fast start, less ops overhead. - Desktop only — No cloud. Best for: single-user desktop applications. ### 3. Networking - VPC: Network isolation, subnets (public/private) - DNS: Domain management, Route53/Cloudflare - Load balancing: ALB/NLB, health checks, SSL termination - CDN: Static asset distribution, edge caching ### 4. Infrastructure as Code Choose one: - AWS CDK — TypeScript/Python, AWS-native. Best for: AWS-only, programmatic infra. - Terraform — HCL, multi-cloud. Best for: cloud-agnostic, declarative. - Pulumi — General-purpose languages. Best for: developers who prefer Python/TS. - CloudFormation — YAML/JSON, AWS-native. Best for: simple AWS setups. - None — Manual/console setup. Best for: prototypes, desktop apps. ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `INFRA_LOCAL` - `INFRA_CLOUD` - `INFRA_K8S` Report coverage and gaps. --- ## Deliverables - ✅ Local dev environment defined with provisioning instructions - ✅ Cloud provider & compute model chosen with rationale - ✅ Networking architecture defined - ✅ IaC tool selected - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define CI/CD Pipeline	DTA-10	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-10 Define CI/CD Pipeline' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define CI/CD Pipeline ## Objective Choose CI platform, define pipeline stages, configure artifact registry, set promotion gates, and establish trunk-based development flow. --- ## Decisions to Make ### 1. CI Platform Choose one: - GitHub Actions — GitHub-native, YAML workflows. Best for: GitHub-hosted repos. - GitLab CI — GitLab-native, `.gitlab-ci.yml`. Best for: GitLab-hosted repos. - Jenkins — Self-hosted, Groovy pipelines. Best for: complex custom pipelines. - CircleCI — Cloud-hosted, YAML config. Best for: fast builds, Docker-native. - None — Local-only builds. Best for: desktop apps, early prototypes. ### 2. Pipeline Stages Define the standard pipeline stages: ``` lint → test → build → publish → deploy ``` For each stage: - What runs? (commands, scripts) - What triggers it? (push, PR, tag, manual) - What blocks the next stage? (failure criteria) - Estimated duration target ### 3. Artifact Registry - Container images: Docker Hub, ECR, GCR, GitHub Container Registry - Packages: npm registry, PyPI, private registry - Build artifacts: S3, GCS, artifact storage in CI platform - Retention policy: How long are artifacts kept? ### 4. Promotion Gates - Automated gates: All tests pass, linting clean, security scan clean - Manual gates: Human approval for production deploy - Environment promotion: dev → staging → production - Rollback trigger: Automated on health check failure? Manual only? ### 5. Trunk-Based Development Flow - Branch strategy: Trunk-based (short-lived feature branches, merge to main) - PR requirements: Reviews, CI pass, no conflicts - Merge strategy: Squash, rebase, merge commit - Release tagging: Semantic versioning, automated changelog ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `CICD_BUILD` - `CICD_DEPLOY` - `CICD_PIPELINE` Report coverage and gaps. --- ## Deliverables - ✅ CI platform chosen - ✅ Pipeline stages defined with triggers and gates - ✅ Artifact registry configured - ✅ Promotion gates established - ✅ Trunk-based flow documented - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Release & Rollback	DTA-11	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-11 Define Release & Rollback' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Release & Rollback ## Objective Choose deployment strategy, define version tagging, establish rollback triggers and procedures, and set release cadence. --- ## Decisions to Make ### 1. Deployment Strategy Choose one: - Blue-Green — Two identical environments, switch traffic. Best for: zero-downtime, instant rollback. - Canary — Gradual traffic shift to new version. Best for: risk mitigation, large user base. - Rolling Update — Replace instances one by one. Best for: K8s default, resource-efficient. - Recreate — Stop old, start new. Best for: stateful apps, dev environments. - Feature Flags — Deploy code dark, enable via flags. Best for: decoupling deploy from release. ### 2. Version Tagging & Changelog - Semantic Versioning: MAJOR.MINOR.PATCH - Tagging: Git tags on release commits - Changelog generation: Automated from commit messages (conventional commits) - Release notes: Automated or manual? Where published? ### 3. Rollback Triggers - Automated: Health check failures, error rate spike, latency threshold - Manual: Operator decision, customer report - Rollback procedure: Revert traffic? Redeploy previous version? DB rollback? - Rollback time target: How fast must rollback complete? ### 4. Release Cadence & Policies - Cadence: Continuous delivery (every merge)? Weekly? Sprint-aligned? - Freeze policies: Code freeze before major releases? - Hotfix process: How are urgent fixes deployed outside normal cadence? - Communication: Who is notified of releases? How? ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `RELEASE_DEPLOY` - `RELEASE_ROLLBACK` Report coverage and gaps. --- ## Deliverables - ✅ Deployment strategy chosen with rationale - ✅ Version tagging and changelog approach defined - ✅ Rollback triggers and procedures established - ✅ Release cadence and policies documented - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Observability	DTA-12	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-12 Define Observability' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Observability ## Objective Define logging, metrics, distributed tracing, dashboards, alerting, and incident response approach. --- ## Decisions to Make ### 1. Logging - Format: Structured logging (JSON) vs. plain text - Library: Python logging, structlog, loguru - Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL — when to use each - Aggregation: CloudWatch, ELK stack, Loki, local file rotation - Retention: How long are logs kept? Per environment? - Sensitive data: What must NOT be logged? (passwords, tokens, PII) ### 2. Metrics - Application metrics: Request count, response time, error rate, queue depth - Infrastructure metrics: CPU, memory, disk, network - Business metrics: Features used, user actions, conversion rates - Tools: Prometheus, CloudWatch Metrics, Datadog, StatsD - Naming convention: `app.request.duration`, `app.db.query.count` ### 3. Distributed Tracing - Correlation IDs: How are requests traced across services/processes? - Span collection: OpenTelemetry, Jaeger, Zipkin, X-Ray - Trace sampling: Sample all requests or a percentage? - Trace context propagation: How are trace IDs passed between services? ### 4. Dashboards & Alerting - Dashboard tool: Grafana, CloudWatch Dashboards, Datadog - SLIs/SLOs: Service Level Indicators and Objectives - e.g., "99.9% of requests complete in < 500ms" - e.g., "Error rate < 0.1%" - Alert channels: Email, Slack, PagerDuty, OpsGenie - Alert severity levels: P1 (page immediately) through P4 (review next day) ### 5. Incident Response - Runbooks: Standard operating procedures for common incidents - Postmortems: Blameless postmortem template and cadence - On-call rotation: Who is on call? How are they reached? - Escalation path: P1 → on-call → team lead → management ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `OBS_LOGGING` - `OBS_METRICS` - `OBS_TRACING` Report coverage and gaps. --- ## Deliverables - ✅ Logging strategy defined (format, aggregation, retention) - ✅ Metrics approach chosen (tools, naming, key metrics) - ✅ Distributed tracing configured (if applicable) - ✅ Dashboards & alerting defined (SLIs/SLOs, alert channels) - ✅ Incident response procedures established - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Config & Secrets	DTA-13	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-13 Define Config & Secrets' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Config & Secrets ## Objective Define environment configuration strategy, secrets management, feature flag approach, and per-environment overrides. --- ## Decisions to Make ### 1. Environment Configuration - Config source: Environment variables, config files (.env, YAML, TOML), Django settings - Per-environment overrides: How do dev/staging/prod configs differ? - Config validation: Are required configs validated at startup? - Config documentation: Where are all config options documented? Example patterns: ``` # .env file (local) DEBUG=True DATABASE_URL=sqlite:///db.sqlite3 SECRET_KEY=dev-only-key # Production (env vars from secrets manager) DEBUG=False DATABASE_URL=postgresql://... SECRET_KEY=<from-vault> ``` ### 2. Secrets Management Choose approach: - Environment variables — Simple, works everywhere. Risk: leakage in logs/errors. - Secrets manager — AWS Secrets Manager, HashiCorp Vault, Azure Key Vault. Best for: production. - Sealed secrets — Encrypted in Git, decrypted in cluster. Best for: GitOps. - .env files — Local only, gitignored. Best for: development. - Django's SECRET_KEY rotation — How often? How to rotate without downtime? ### 3. Feature Flags - Approach: Config-based, database-based, external service (LaunchDarkly, Unleash) - Flag types: Boolean (on/off), percentage rollout, user segment - Management: Who can toggle flags? Via UI, CLI, API? - Cleanup: How are stale flags removed? ### 4. Scan Skills Query Playbook Skills where `capability_domain` in: - `CONFIG_ENV` - `CONFIG_SECRETS` - `CONFIG_FLAGS` Report coverage and gaps. --- ## Deliverables - ✅ Environment configuration strategy defined - ✅ Secrets management approach chosen - ✅ Feature flag approach defined (if applicable) - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Security	DTA-14	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-14 Define Security' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Security ## Objective Define authentication model, authorization approach, API security measures, dependency scanning, and OWASP compliance targets. --- ## Decisions to Make ### 1. Authentication Model Choose one: - Session-based — Server-side sessions, cookie-based. Best for: traditional web apps. - JWT — Stateless tokens. Best for: SPAs, mobile apps, microservices. - OAuth2/OIDC — Delegated auth via provider. Best for: SSO, social login. - API keys — Simple key-based auth. Best for: machine-to-machine. - mTLS — Mutual TLS. Best for: service-to-service in zero-trust. Decide: - Password hashing algorithm (bcrypt, Argon2, PBKDF2) - Session/token lifetime and refresh strategy - MFA requirements (if any) - Password complexity rules ### 2. Authorization Model Choose one: - RBAC — Role-Based Access Control. Roles → Permissions. Best for: most web apps. - ABAC — Attribute-Based Access Control. Policy rules on attributes. Best for: complex permission logic. - Object-level — Per-object ownership checks. Best for: multi-tenant apps. - Hybrid — RBAC for coarse-grained + object-level for fine-grained. Define permission model: - What roles exist? - What can each role do? - How are permissions checked in code? (decorators, middleware, service layer) ### 3. API Security - Rate limiting: Per-user, per-endpoint, per-IP - CORS: Allowed origins, methods, headers - Input validation: Where validated? (serializer, model, view) - CSRF protection: Tokens, SameSite cookies - Content Security Policy: CSP headers configuration ### 4. Dependency Scanning - Tool: Dependabot, Snyk, pip-audit, npm audit, Trivy - Cadence: On every PR? Nightly? Weekly? - Policy: Block merge on critical CVEs? Warning only? - License compliance: Check for incompatible licenses? ### 5. OWASP Compliance Target OWASP Top 10 coverage: - A01: Broken Access Control - A02: Cryptographic Failures - A03: Injection - A05: Security Misconfiguration - A07: Identification and Authentication Failures For each: current mitigation strategy. ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `SEC_AUTH` - `SEC_AUTHZ` - `SEC_API` - `SEC_SCAN` Report coverage and gaps. --- ## Deliverables - ✅ Authentication model chosen with configuration details - ✅ Authorization model defined with role/permission structure - ✅ API security measures configured - ✅ Dependency scanning tool and policy established - ✅ OWASP compliance targets set - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Backup & Recovery	DTA-15	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-15 Define Backup & Recovery' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Backup & Recovery ## Objective Define backup schedule, retention policy, RTO/RPO targets, disaster recovery plan, and data export/import procedures. --- ## Decisions to Make ### 1. Backup Schedule & Retention - Backup frequency: Hourly, daily, weekly, continuous (WAL archiving) - Backup type: Full, incremental, differential - Retention policy: How long are backups kept? - Daily backups: keep 7 days - Weekly backups: keep 4 weeks - Monthly backups: keep 12 months - Storage: Where are backups stored? (S3, GCS, local disk, off-site) - Encryption: Are backups encrypted at rest? ### 2. RTO & RPO Targets - RPO (Recovery Point Objective): Maximum acceptable data loss - e.g., "15 minutes" means we can lose at most 15 minutes of data - RTO (Recovery Time Objective): Maximum acceptable downtime - e.g., "1 hour" means the system must be restored within 1 hour - These targets drive backup frequency and recovery procedure complexity ### 3. Disaster Recovery Plan - Failover: Automatic or manual? - Geo-redundancy: Multi-region, multi-AZ, single region? - Recovery procedure: Step-by-step restoration from backup - DR testing: How often is the recovery procedure tested? - Communication plan: Who is notified during a disaster? ### 4. Data Export/Import - Export formats: JSON, CSV, SQL dump, custom format - Export triggers: Manual, scheduled, API-driven - Import validation: How is imported data validated? - Makefile targets: `make backup`, `make restore`, `make export-data` ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `BACKUP_DB` - `BACKUP_DR` Report coverage and gaps. --- ## Deliverables - ✅ Backup schedule and retention policy defined - ✅ RTO/RPO targets set with rationale - ✅ Disaster recovery plan documented - ✅ Data export/import procedures defined - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Developer Experience	DTA-16	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-16 Define Developer Experience' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Developer Experience ## Objective Define IDE setup, code quality tooling, local debugging approach, onboarding flow, and inner loop speed targets. --- ## Decisions to Make ### 1. IDE Setup - Recommended IDE: VS Code, PyCharm, Cursor, Windsurf, etc. - Extensions/plugins: Which are required? Which are recommended? - Workspace settings: Shared `.vscode/settings.json` or `.idea/` config - Debug configurations: Launch configs for backend, frontend, tests - AI assistant config: MCP server configuration for Mimir integration ### 2. Code Quality Tooling - Linter: flake8, ruff, pylint, eslint - Formatter: black, ruff format, prettier - Type checker: mypy, pyright - Pre-commit hooks: Which checks run before commit? - Configuration files: `pyproject.toml`, `.flake8`, `.prettierrc` - Makefile targets: `make lint`, `make format`, `make typecheck` ### 3. Local Debugging - Breakpoint debugging: IDE debugger, pdb, ipdb - Log tailing: How to watch logs in real-time during development - DB inspection: Django admin, DB browser, management commands - Network inspection: How to inspect HTTP requests (Django Debug Toolbar) - Test debugging: How to run and debug individual tests ### 4. Onboarding - README: What must be in the root README for a new developer? - `make provision`: Single command to install all prerequisites - `make run`: Single command to start the full application - Time-to-first-feature target: "New developer ships first feature within X hours" - Onboarding checklist: Step-by-step from `git clone` to running tests ### 5. Inner Loop Speed - Hot reload: Auto-restart on file changes (Django runserver, webpack HMR) - Incremental builds: Only rebuild what changed - Test watch mode: Auto-run affected tests on save - Build performance: Target build times per operation ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `DEVEX_IDE` - `DEVEX_QUALITY` - `DEVEX_ONBOARD` Report coverage and gaps. --- ## Deliverables - ✅ IDE setup documented with recommended extensions and debug configs - ✅ Code quality tooling configured (linter, formatter, pre-commit) - ✅ Local debugging approach defined - ✅ Onboarding flow documented with time-to-first-feature target - ✅ Inner loop speed targets set - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define Documentation Strategy	DTA-17	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-17 Define Documentation Strategy' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Documentation Strategy ## Objective Define Architecture Decision Record (ADR) process, API documentation approach, living documentation standards, runbook format, and knowledge base structure. --- ## Decisions to Make ### 1. Architecture Decision Records (ADRs) - Template: Standard ADR format (Title, Status, Context, Decision, Consequences) - Storage location: `docs/architecture/decisions/` or `docs/adr/` - Numbering: Sequential (ADR-001, ADR-002, ...) - Review process: PR-based? Team discussion? Informal? - When to write: Any significant architecture or technology choice ### 2. API Documentation - Approach: OpenAPI/Swagger spec generation - Generation: Contract-first (write spec, generate code) or code-first (generate spec from code) - Publishing: Auto-published on build? Swagger UI endpoint? - MCP tool documentation: How are MCP tools documented? - Versioning: Spec versioned with API version ### 3. Living Documentation - Code comments policy: When to comment (non-obvious logic), when NOT to comment (obvious code) - Docstring standards: Sphinx format with `:param:`, `:return:`, `:raises:` and examples - Type hints: Required on all public methods and functions - README hierarchy: Root README → app-level READMEs → module docs ### 4. Runbook Standards - Format: Markdown with structured sections (Trigger, Impact, Steps, Verification) - Storage: `docs/runbooks/` or alongside infrastructure code - Update cadence: After every incident that reveals a gap - Review: Quarterly runbook review for staleness ### 5. Knowledge Base - Wiki: GitHub Wiki, Confluence, Notion, or docs/ in repo - Onboarding guides: For new developers, new operators - FAQ: Common questions and troubleshooting - Search: How is documentation discoverable? ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `DOCS_ADR` - `DOCS_API` - `DOCS_RUNBOOK` Report coverage and gaps. --- ## Deliverables - ✅ ADR process established with template and storage location - ✅ API documentation approach chosen - ✅ Living documentation standards defined (comments, docstrings, type hints) - ✅ Runbook standards set - ✅ Knowledge base structure defined - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
Define MCP Architecture	DTA-18	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-18 Define MCP Architecture' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define MCP Architecture Condition: Run only if the system exposes tools or resources via the Model Context Protocol. Skip and write "Not applicable" in SAO §18 if MCP is not in scope. Depends on DTA-03 (API style chosen). Reference: Playbook artifact MCP FastMCP Reference Architecture (latest released Edda version). ## Objective Decide the MCP integration case (A / B / hybrid), transport topology, tool inventory, and authentication pattern; document all decisions in SAO §18. ## Process 1. Fetch the latest MCP FastMCP Reference Architecture from the playbook and read the Purpose & Mission Assessment sections before answering any question below. 2. Answer mission questions — determine integration case and transport. 3. Inventory tools — decide which service callables become MCP tools. 4. Design auth pattern — process user, PAT per call, or both. 5. Handle stdout hygiene if stdio transport is selected. 6. Record decisions for SAO §18. ## Decisions to Make ### 1. Mission Assessment (Q1–Q7) \| # \| Question \| Answer \| Impact \| \|---\|----------\|--------\|--------\| \| Q1 \| Who are the MCP clients? (AI IDE, Claude Desktop, custom script, cloud AI) \| \| Transport and auth \| \| Q2 \| Embed business logic or delegate to HTTP API? \| \| Case A vs B vs hybrid \| \| Q3 \| How is user identity established per tool call? \| \| Auth pattern \| \| Q4 \| Are any tools destructive? (write, delete, deploy) \| \| HITL and write-tool policy \| \| Q5 \| Low-latency local IDE integration required? \| \| stdio transport \| \| Q6 \| Multi-tenant or remote-client access required? \| \| HTTP+SSE transport \| \| Q7 \| Stdout logging interference needs prevention? \| \| Log routing for stdio \| ### 2. Integration Case - [ ] Case A — Service Bridge: MCP calls internal service layer directly. Best for single-deployment systems. - [ ] Case B — API Facade: MCP calls the public HTTP API. Best for multi-tenant / remote clients. - [ ] Hybrid: Mix of A and B. Rationale: _____ ### 3. Transport Topology \| Target \| Transport \| Port / Path \| Notes \| \|--------\|-----------\|-------------\|-------\| \| Local IDE (Cursor, Claude Desktop) \| stdio \| n/a \| Requires stdout hygiene \| \| Remote AI clients \| HTTP+SSE \| :8001/mcp \| Auth header required \| Topology decision: stdio only / HTTP+SSE only / Both (dual server) ### 4. Tool Inventory \| Tool name \| Service method \| Write? \| HITL? \| Case \| \|-----------\|----------------\|--------\|-------\|------\| \| \| \| \| \| \| Write-tool policy: Require explicit confirmation param / HITL prompt before execute / Audit log only ### 5. Authentication Pattern Selected pattern(s): Process user / PAT per call / Session cookie / Mixed PAT injection point: Tool argument (explicit) / HTTP header (Bearer — avoids prompt injection) ### 6. Stdout Hygiene (if stdio) - Redirect all logging to stderr or file - Suppress third-party libraries that print to stdout - Add T3 test verifying no stdout noise on server boot ### 7. Case B: API Readiness Contract (if Case B or hybrid) \| Tool \| HTTP endpoint \| Method \| Auth header \| \|------\|---------------\|--------\|-------------\| \| \| \| \| \| ### 8. Scan Skills Query Skills where `capability_domain` in: MCP, API_INTEGRATION, AUTH. Report gaps. ## Deliverables - Mission questions answered (Q1–Q7) - Integration case chosen (A / B / hybrid) with rationale - Transport topology defined - Tool inventory table (tool → service method → write? → HITL?) - Auth pattern defined with injection point - Stdout hygiene addressed (if stdio) - API readiness contract defined (if Case B) - Skill coverage assessed - Decision recorded for SAO §18 (DTA-18)
Define AI Agent Architecture	DTA-19	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-19 Define AI Agent Architecture' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define AI Agent Architecture Condition: Run only if the system has in-app LLM agents (agentic loops, plan/worker execution, or LLM calls inside the application). Skip and write "Not applicable" in SAO §17 if none of: in-app agentic loop, LLM calls initiated by the app, plan/worker execution. Reference: Playbook artifact AI Agent Reference Architecture (latest released Edda version). ## Objective Confirm components (Part 1), pick design patterns and scenarios (Part 2), choose serving mode (Part 3), select capabilities (`CAP-xxx`), choose an assembly template, and record decisions in SAO §17. ## Process 1. Fetch the latest AI Agent Reference Architecture from the playbook. 2. Read How to use this document and Part 1 — Components; complete infra, model, vector (if needed), framework, memory, and observability checklist in SAO §17. 3. Pick Part 2 — Design patterns and primary SC-xx scenario(s); use Part 5 — Quick reference for secondary CAP additions. 4. Choose Part 3 — Serving mode (real-time, batch/queue, or both). 5. Copy required + chosen optional CAP-IDs into SAO §17 from Part 4.1 Capability table. 6. Confirm dependencies in Part 4.3 Module wiring. 7. Note starting assembly template from Part 4.4 (T-01, T-02, T-03, or T-00 custom). 8. Name integration proof test IDs (`PRF-SCxx-xx`, `PRF-OBS-01`) from Part 4.5 as DoD gate. 9. If both SC-02 and SC-05 are selected, read Pattern 5 · SC-02 × SC-05 · Full rescan invariants and record checklist in SAO §17. 10. If Pattern 4 / SC-01 with large domain state, decide dual execution path (CAP-037, CAP-038, CAP-039) and memory tiers (Component 5 / CAP-091–094). 11. Record Pattern 4 anti-pattern checklist (mechanical step execution; worker failure bridge) when CAP-060 selected. 12. Record decisions for SAO §17 via Write SAO.md (Activity 59). ## Decisions to Make ### 1. Infra layer (Component 1) \| Decision \| Choice \| Rationale \| \|----------\|--------\|-----------\| \| LLM provider \| anthropic / openai / ollama / … \| \| \| Ollama readiness probe at startup \| Yes / No / N/A \| \| \| Broker + result backend (CAP-060) \| Configured / N/A \| \| \| Secrets server-side only \| Yes \| \| ### 2. Vector tier (Component 3) \| Decision \| Choice \| Rationale \| \|----------\|--------\|-----------\| \| Vector store needed \| Yes / No \| \| \| Backend \| pgvector / dedicated / in-process \| \| \| CAP-090 / CAP-094 selected \| Yes / No \| \| ### 3. Design pattern & scenario selection Read Part 2 pattern sections before ticking. Record primary scenario(s) and rationale. \| SC-ID \| Pattern \| Name \| Selected? \| Rationale \| \|-------\|---------\|------\|-----------\|-----------\| \| SC-01 \| 4 \| Conversational planner \| \| \| \| SC-02 \| 2 \| Field extractor / batch ingest \| \| \| \| SC-03 \| 7 \| Compiled pipeline \| \| \| \| SC-04 \| 3 \| Event-driven nudge \| \| \| \| SC-05 \| 5 \| Governed mutations \| \| \| ### 4. Serving mode (Part 3) \| Mode \| Selected? \| CAP-IDs \| \|------\|-----------\|---------\| \| Real-time (3.1) \| \| CAP-040, CAP-003, CAP-100 \| \| Batch / queue (3.2) \| \| CAP-060–066 \| \| Observability for serving (3.3) \| \| CAP-101, CAP-100 \| ### 5. Dual execution path (Pattern 4 / SC-01 with large state) \| Decision \| Choice \| Rationale \| \|----------\|--------\|-----------\| \| Context snapshot in chat (CAP-037) \| Yes / No \| \| \| Snapshot invalidation on writes (CAP-038) \| Yes / No \| \| \| Mutation-only tools in conversation (CAP-039) \| Yes / No \| \| \| Full tool registry in plan worker only \| Yes / No \| \| ### 6. Memory tiers (Component 5) \| Tier \| CAP-IDs \| Selected? \| Rationale \| \|------\|---------\|-----------\|-----------\| \| 1 Hot snapshot \| 037, 038, 039 \| \| \| \| 2 Semantic search \| 091 \| \| \| \| 3 AI profile \| 092 \| \| \| \| 4 Reference library \| 094, 090 \| \| \| \| 5 Entity notes \| 093 \| \| \| ### 7. Capability checklist From Part 4.1 — tick every CAP your project implements: \| CAP-ID \| Name \| Required for SC? \| Implement? \| Module path in project \| \|--------\|------\|------------------\|------------\|------------------------\| \| CAP-001 \| LLM Port protocol \| \| \| \| \| CAP-037 \| Context snapshot hydration \| \| \| \| \| CAP-038 \| Snapshot invalidation hooks \| \| \| \| \| CAP-039 \| Dual tool exposure \| \| \| \| \| CAP-091 \| Semantic context search \| \| \| \| \| CAP-092 \| AI-managed profile memory \| \| \| \| \| CAP-093 \| Entity notes graph \| \| \| \| \| CAP-094 \| Reference knowledge library \| \| \| \| \| CAP-101 \| Agent interaction trace \| \| \| \| \| … \| (copy remaining rows for each selected CAP) \| \| \| \| Minimum: all required CAP-IDs from your selected SC-xx row in Part 5 — Scenario index. ### 8. Assembly template - [ ] T-01 Planner (SC-01 / Pattern 4) - [ ] T-02 Field (SC-02 / Pattern 2) - [ ] T-03 Pipeline (SC-03) - [ ] T-00 Custom — list CAP-IDs: _______________ ### 9. Agent identities (CAP-121, CAP-122) \| Identity \| Role \| Model tier \| Allowed tools \| \|----------\|------\|------------\|---------------\| \| \| \| planning / execution / field \| \| ### 10. Agent Blackboard (if CAP-070 selected) - Durability tier: A — in-process / B — run-persistent - Schema keys: phase, hypothesis, current_plan, last_actions, next_intent - Max board size (chars): ______ ### 11. Worker anti-patterns (if CAP-060 selected) - [ ] Worker uses LLM per step (CAP-054) — not mechanical tool script (Pattern 4 anti-patterns) - [ ] Worker failure bridged to UI (CAP-100 plan_failed and/or chat context injection) - [ ] PRF-SC01-06 mapped if hybrid worker is new ### 12. Observability (Component 6 / CAP-101) - correlation_id header/name: ______ - Cost rate table location: ______ - PRF-OBS-01 test file: ______ ### 13. Integration proof (DoD gate) \| PRF ID \| Scenario \| Test file \| Selected? \| \|--------\|----------\|-----------\|-----------\| \| PRF-SC02-01 \| SC-02 thinking JSON \| \| \| \| PRF-SC02-02 \| SC-02 parse fail loud \| \| \| \| PRF-SC02-03 \| SC-02 domain D0 pre-filter \| \| \| \| PRF-SC02-04 \| SC-02 D1 parse fail loud \| \| \| \| PRF-SC01-01 \| SC-01 plan handoff \| \| \| \| PRF-SC01-02 \| SC-01 429 retry \| \| \| \| PRF-SC01-03 \| SC-01 blackboard retain \| \| \| \| PRF-SC01-04 \| SC-01 dual tool exposure \| \| \| \| PRF-SC01-05 \| SC-01 snapshot invalidation \| \| \| \| PRF-SC01-06 \| SC-01 no mechanical worker \| \| \| \| PRF-SC01-07 \| SC-01 worker failure bridge \| \| \| \| PRF-SC05-01 \| SC-05 HITL \| \| \| \| PRF-SC05-02 \| SC-02+05 full rescan invariants \| \| \| \| PRF-OBS-01 \| all \| correlation + usage trace \| \| \| ### 14. SC-02 × SC-05 full rescan (if both selected) From Pattern 5 · SC-02 × SC-05 · Full rescan invariants: - [ ] Rescan delete ops meet auto-apply confidence threshold (or rescan disables partial auto-apply) - [ ] ChangeSet apply ordering: deletes → updates → adds when rescan flag is set - [ ] PRF-SC05-02 mapped to integration test file ### 15. Scan Skills Query Skills where `capability_domain` in: AI_AGENT, LLM_INTEGRATION, ASYNC_TASK, OBSERVABILITY. Report gaps. ### 16. Task performance quality (TASK-) From artifact 56 Part 4.6 — Task performance quality. Mirror the Part 4.5 Integration proof* table style. These are lane 4 evals — measure model + prompt + tools against structured ground truth, not orchestration wiring (lane 1) or deterministic parse/validate (lane 2). \| TASK ID \| Scenario \| Oracle type \| Pass band \| Selected? \| Test file \| \|---------\|----------\|-------------\|-----------\|-----------\|-----------\| \| TASK-SC02-01 \| SC-02 \| set_recall \| recall ≥ 0.95, extras ≤ 1 \| \| \| \| TASK-SC02-02 \| SC-02 \| graph_diff \| zero unexpected deletes on rescan corpus \| \| \| \| TASK-SC01-01 \| SC-01 \| plan_steps \| expected tool sequence + final state \| \| \| \| TASK-SC05-01 \| SC-05 \| hitl_rate \| destructive ops blocked until approval \| \| \| \| … \| (copy remaining Part 4.6 rows for selected SC-xx) \| \| \| \| \| Eval vs merge DoD: \| Gate \| Lanes \| When \| Blocks merge? \| \|------\|-------\|------\|---------------\| \| Merge DoD \| 1–2 \| PR when `AGENTS_ENABLED=true` \| Yes — PRF-* under CAP-004 ScriptedLLM; lane 2 deterministic shell in normal integration \| \| Contract eval \| 3 \| Nightly / optional CD cert \| No — temp=0 schema/contract bounds only \| \| Promotion DoD \| 4 \| `make test-agent-quality` / scheduled eval \| No — regression vs last certified TASK-* band; human promotion decision \| Record chosen TASK rows, fixture paths (`tests/fixtures/agent_tasks/<task-id>/`), and certified pass bands in SAO §17. Full catalog fields (`fixture_ref`, `n_runs`, oracle asserts) live in artifact 56 Part 4.6 — link there; do not duplicate prose in SAO. ## Deliverables - Infra + vector tier decisions documented - Primary pattern(s) and SC-xx scenario(s) chosen with rationale - Serving mode (Part 3) selected - Dual execution path + memory tier decisions (when Pattern 4 / SC-01) - CAP-ID checklist complete for selected scenarios - Assembly template (T-01 / T-02 / T-03 / T-00) named - Agent identities + model tiers documented - Worker anti-pattern checklist completed (when CAP-060) - Observability trace documented (CAP-101) - PRF test IDs mapped to project test files - TASK-* rows mapped to golden task fixtures (when lane 4 in scope) - SC-02 × SC-05 rescan checklist completed (when both scenarios selected) - Skill coverage assessed - Decision recorded for SAO §17 via Write SAO.md (Activity 59)
Write SAO.md	DTA-20	Define Architecture	Junior Edda	Inception (#1)	Read the 'DTA-20 Write SAO.md' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. Position in workflow: Terminal activity of Define Architecture (DTA) — order 20 of 20. Run only after all prior DTA domain activities are complete (DTA-02 through DTA-17, and when applicable Activity 200 Define AI Agent Architecture and Activity 201 Define MCP Architecture). # Write SAO.md (System Architecture Overview) ## Objective Compile all architectural decisions from DTA-02 through DTA-17 (and optionally Activities 200 and 201, if applicable) into a single, authoritative document: `docs/architecture/SAO.md`. Since Activity 42 now dispatches the domain decision workers in parallel (see that activity's Step 6), this activity is the first point at which all 16-18 domain decisions are seen together. Serial execution used to give an agent incidental cross-domain awareness just by having read every earlier decision in order before reaching this activity; parallel dispatch does not provide that awareness, so Step 0 below makes the check explicit instead of assuming it happened. ## Process ### 0. Cross-Domain Consistency Check (run before compiling) Before writing anything into SAO.md, check each collected domain decision against the others for contradictions. At minimum, check these known collision points: \| Pair \| What can conflict \| \|---\|---\| \| Security (decision from the Define Security domain activity) ↔ Data Architecture (Define Data Architecture) \| Authentication model and encryption-at-rest expectations must match the chosen database engine's actual support (e.g. field-level encryption availability, session storage backing) \| \| Infrastructure (Define Infrastructure) ↔ CI/CD Pipeline (Define CI/CD Pipeline) \| The chosen compute model (Kubernetes, container service, serverless, VMs, PaaS, desktop-only) constrains which deploy targets and promotion mechanisms are even possible \| \| Infrastructure (Define Infrastructure) ↔ Release & Rollback (Define Release & Rollback) \| The blue/green or rollback mechanism chosen must match the compute model — e.g. a Kubernetes/EKS choice implies namespace or Route53-weight based switching; an Elastic Beanstalk choice implies environment-swap based switching. A Release & Rollback decision written independently of the Infrastructure decision may assume a mechanism the chosen compute platform doesn't support. \| For each pair above (and any other conflict a reviewer notices while compiling): if the two decisions are compatible, note nothing extra. If they conflict, do not silently pick one — surface it to the user as a named contradiction between the two domains and get an explicit resolution before writing either section into SAO.md. Record the outcome of this check (clean, or list of resolved contradictions) as a short note at the top of SAO.md's changelog/history, so a future reader can see the check happened. ### 1. Gather All Decisions Collect recorded decisions from each domain activity: - DTA-02: Application Blocks - DTA-03: Integration & API Design - DTA-04: Code Organization - DTA-05: Data Architecture - DTA-06: Test Strategy - DTA-07: Performance & Scalability - DTA-08: Error Handling & Resilience - DTA-09: Infrastructure - DTA-10: CI/CD Pipeline - DTA-11: Release & Rollback - DTA-12: Observability - DTA-13: Config & Secrets - DTA-14: Security - DTA-15: Backup & Recovery - DTA-16: Developer Experience - DTA-17: Documentation Strategy - Activity 200: AI Agent Architecture (if applicable) - Activity 201: MCP Architecture (if applicable) ### 2. Write SAO.md Structure — add sections 17 and 18 after section 16: ``` ## 16. Documentation Strategy [Decision from DTA-17] ## 17. AI Agent Architecture [Decision from Activity 200 — skip section if no in-app agent] ## 18. MCP Architecture [Decision from Activity 201 — skip section if no MCP interface] ``` ### 3. Skill Gap Analysis Compile coverage reports from all domain activities into a single matrix: ``` Domain \| Covered Skills \| Gaps Application Blocks \| [list] \| [list] ... AI Agent Architecture \| [list] \| [list] MCP Architecture \| [list] \| [list] ``` ### 4. Review with User Present SAO.md for review, including the Step 0 consistency-check outcome. Get explicit approval before proceeding to Bootstrap Project. ### 5. Post-Implementation Updates The SAO is a living document. During and after implementation, update it with critical discoveries, retrospective corrections, and recurring patterns. Each update should reference the original DTA decision. ## Deliverables - Cross-domain consistency check performed and recorded (Step 0), any contradictions resolved with the user before compilation - SAO.md written at `docs/architecture/SAO.md` - All domain decisions (16 core + up to 2 optional: AI Agent, MCP) compiled - Skill coverage report included - Key decisions summary with rationale - User approval obtained - Ready to proceed to Define Software Process (DSP). DSP requires SAO.md to generate the AI IDE configuration — run DSP before BSP. When ESM, DTA, DSP, and BSP are all complete, proceed to BSP-08 for the Construction Handoff and mode selection.
Verify ESM Artifacts	DSP-1	Deploy Software Process	Junior Edda	Elaboration (#2)	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: playbook workflow `Envision_the_System/_workflow.md` (Junior Edda export). 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
Verify DTA Artifacts	DSP-2	Deploy Software Process	Junior Edda	Elaboration (#2)	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: playbook workflow `Define_Architecture/_workflow.md` (Junior Edda export). 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
Verify Architecture & Code Organization	DSP-3	Deploy Software Process	Junior Edda	Elaboration (#2)	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 the Junior Edda playbook export (e.g. `.cursor/playbooks/Edda/`) 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 the playbook `skills/` directory): ``` Available Skills: skills/ \| N skills found (others) \| ... ``` Scan for available artifact templates: ``` Available Artifact Templates: artifacts/ \| User_Journey_Template.md, Feature_File_Template_Gherkin.md, IA_Guidelines_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 \| ✅ Build_Feature/ (Junior Edda playbook export) Skills available \| ✅ N skills in skills/ Artifact templates \| ✅ templates in artifacts/ ``` --- ## 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
Choose Target AI IDE	DSP-4	Deploy Software Process	Junior Edda	Elaboration (#2)	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)
Generate AI IDE Configuration	DSP-5	Deploy Software Process	Junior Edda	Elaboration (#2)	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.
Review & Commit	DSP-6	Deploy Software Process	Junior Edda	Elaboration (#2)	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.
Assess Estimation Readiness	EST-1	Estimate the Project	Junior Edda	Elaboration (#2)	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
Calibrate Reference Stories	EST-2	Estimate the Project	Junior Edda	Elaboration (#2)	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).
Size Scenarios (Level 1 SWAG)	EST-3	Estimate the Project	Junior Edda	Elaboration (#2)	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
Assess Risk Multipliers	EST-4	Estimate the Project	Junior Edda	Elaboration (#2)	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
Produce Rough Estimates + AFP	EST-5	Estimate the Project	Junior Edda	Elaboration (#2)	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).
Decompose Work Packages (Level 2)	EST-6	Estimate the Project	Junior Edda	Elaboration (#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. Each work package's BPE-01 dry-run is independent of every other package — it reads only that package's own scenario file, screen, and SAO.md, and never another package's plan. That independence is what this activity now dispatches on (Step 2, below) instead of working through packages one at a time. ## 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. ## Step 1: Enumerate Work Packages List every undecomposed work package from the sprint plan (EST-05 output). For each, identify the three inputs it will need: 1. The scenario file — `docs/features/{act}/{feature}.feature` 2. The screen — the matching node in the dialogue map (`docs/architecture/screen-flow.drawio`) 3. SAO.md — the authoritative architecture and stack description (shared by every package — read-only, not a conflict) This list is the dispatch unit for Step 2. ## Step 2: Dispatch Estimation Workers (parallel) Apply rule `do-fan-out-independent-work`. The item list is every work package enumerated in Step 1. Each worker does the following for its one package, and only its own package: a) 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. b) 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) c) Return the work package record. Each worker's footprint is read-only (its own feature file, screen, and SAO.md) plus a write of exactly one row-group in the WBS Features tab — packages never contend for the same row, so there is nothing to serialize. Return: ``` 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 3: Record All Work Packages Collect every worker's report from Step 2 and enter each into the WBS Features tab. Since each worker wrote a distinct row-group, this is a mechanical merge — no conflict resolution needed. ## Step 4: Cross-Check Against Level 1 Rough Estimate For each work package, compare its Level 2 total to its 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, per package. ## Step 5: Sprint-Level Rollup After all work packages in a sprint are recorded (Steps 2-4 complete for the whole sprint), 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. Repeat Steps 1-5 for the next sprint's packages, highest priority first. ## 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. ### VI. Fan Out, Don't Queue Work packages don't depend on each other's plans — dispatch them in one wave per rule `do-fan-out-independent-work` rather than working through the sprint's packages one at a time. The only genuinely sequential parts are Step 4 (needs a package's own Step 2-3 output) and Step 5 (needs every package in the sprint recorded). ## Success Criteria - BPE-01 Plan executed (estimation mode) for every Level 2 work package, dispatched in parallel per sprint - 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, per package - 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).
Run Monte Carlo Simulation	EST-7	Estimate the Project	Junior Edda	Elaboration (#2)	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
Sprint Close & Rebaseline	EST-8	Estimate the Project	Junior Edda	Elaboration (#2)	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).
Review SAO & Define Infra Requirements	DCI-1	Design & Deploy Cloud Infra	Junior Edda	Elaboration (#2)	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).
Scaffold Infra Repo & CDK Project	DCI-2	Design & Deploy Cloud Infra	Junior Edda	Elaboration (#2)	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
Build VPC & Networking Stack	DCI-3	Design & Deploy Cloud Infra	Junior Edda	Elaboration (#2)	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
Build Compute & Container Registry Stack	DCI-4	Design & Deploy Cloud Infra	Junior Edda	Elaboration (#2)	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).
Build Route53 & DNS Stack	DCI-5	Design & Deploy Cloud Infra	Junior Edda	Elaboration (#2)	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
Create Infra GH Workflow	DCI-6	Design & Deploy Cloud Infra	Junior Edda	Elaboration (#2)	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
Deploy & Verify Cloud Environment	DCI-7	Design & Deploy Cloud Infra	Junior Edda	Elaboration (#2)	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
Review SAO & Define CICD Requirements	DCD-1	Design & Deploy CICD	Junior Edda	Elaboration (#2)	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
Create Helm Chart & Values	DCD-2	Design & Deploy CICD	Junior Edda	Elaboration (#2)	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).
Add Container & Deploy Make Targets	DCD-3	Design & Deploy CICD	Junior Edda	Elaboration (#2)	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).
Build CI Pipeline	DCD-4	Design & Deploy CICD	Junior Edda	Elaboration (#2)	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`.
Build CD Pipeline	DCD-5	Design & Deploy CICD	Junior Edda	Elaboration (#2)	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.
Implement Switch & Rollback	DCD-6	Design & Deploy CICD	Junior Edda	Elaboration (#2)	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)
End-to-End Pipeline Verification	DCD-7	Design & Deploy CICD	Junior Edda	Elaboration (#2)	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).
Verify & Install Prerequisites	BSP-1	Bootstrap Project	Junior Edda	Elaboration (#2)	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
Initialize Repository	BSP-2	Bootstrap Project	Junior Edda	Elaboration (#2)	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).
Scaffold Project Structure	BSP-3	Bootstrap Project	Junior Edda	Elaboration (#2)	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).
Initialize Runtimes & Dependencies	BSP-4	Bootstrap Project	Junior Edda	Elaboration (#2)	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).
Configure Dev Tooling	BSP-5	Bootstrap Project	Junior Edda	Elaboration (#2)	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).
Create Makefile	BSP-6	Bootstrap Project	Junior Edda	Elaboration (#2)	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
Create Welcome Page & Verify	BSP-7	Bootstrap Project	Junior Edda	Elaboration (#2)	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
Configure Observability & Logging	BSP-8	Bootstrap Project	Junior Edda	Elaboration (#2)	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.
Plan Feature	BPE-1	Build Feature	Junior Edda	Construction (#3)	Read the 'BPE-1 Plan Feature' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Plan a new feature implementation by analyzing requirements, assessing codebase state, creating detailed implementation plan, and preparing for execution. ## Prerequisites - Feature specification or idea for what needs to be built - Access to codebase and documentation ## Steps ### Step 0: Reset and Prepare Reset your task plan. If there was work in progress on another task, create a TODO.md file documenting what was being worked on, what was completed, what remains to be done, and any blockers or notes. ### Step 1: Understand Architecture Read `docs/architecture/SAO.md` (if exists) to identify architectural patterns and principles relevant to this implementation. Note which section headings govern this feature — you will need these in Step 6. ### Step 2: Understand User Journey Check `docs/features/user_journey.md` (if exists) to understand what you're building and how it integrates with other parts of the system. ### Step 3: Analyze Feature Specification Read the feature specification thoroughly. If none exists, propose creating one first. Follow BDD/Gherkin format: one scenario = one user goal; 5–10 steps max; GIVEN-WHEN-THEN structure; independently executable. Step phrases must reuse patterns from `docs/features/CATALOG.md` or explicitly add a new catalogued step via TFK-07. ### Step 4: Assess Codebase State a) Identify reusable components: list components/services/models that can be reused; verify they're not stubs. b) Check test coverage: for any reusable components without tests, add test creation to the plan. c) Build context map: identify 3–5 `file:line_range` locations an implementor must read. Format: ``` \| file \| lines \| one-line note \| ``` If you cannot identify 3 meaningful references, the codebase assessment in step (a) is incomplete. d) Detect MCP / Agent surface: - Check SAO §18 — is MCP in scope for this feature? If yes: locate `mcp/server.py` (or equivalent). Verify `initialize_mcp()` exists and is called on startup. If missing: add initialization to the plan before any tool registration step. - Check SAO §17 — does this feature add or extend agent capabilities? If yes: locate `ToolExecutor` (artifact 56 §4.3). Verify it is instantiated and injected into the agent loop. If missing: add ToolExecutor initialization to the plan before service wiring. - Record findings as additional one-liners in the Context Map: `mcp/server.py \| <line> \| FastMCP singleton — register new tools here` `llm/executor.py \| <line> \| ToolExecutor — wire service callables here` Skip a row if that surface is not in scope. ### Step 5: Clarification Questions Ask clarification questions scenario-by-scenario. If >5 questions total, create `FEAT_X.Y.Z_Clarifications.md` for batch answers. ### Step 6: Create Implementation Plan Mandatory Section A — Context Map (from Step 4c) Mandatory Section B — Do-Not-Do List (derived from SAO.md sections) Mandatory Section C — SAO.md Sections That Apply Mandatory Section D — Tests to Create (each row must state what it asserts). When Section E has rows, also list `test__log_story_happy` and/or `test__log_story_reject` (pytest + caplog; integration or view level). When Section G has rows (SAO §17 in scope), also list `test__agent_story_happy` and/or `test__agent_story_reject` (`@pytest.mark.agent_proof`; ScriptedLLM + `assert_agent_story`). Mandatory Section E — Log Story Script (formerly Logs to Emit). Each row is a beat the implementor must emit and prove with caplog. Never defer logging to a final slice. ``` ## Log Story Script \| Where \| Beat \| Trigger \| Must include \| \|-------\|------\|---------\|--------------\| \| `LoginView.post` \| entry \| method called \| email= (never password) \| \| `LoginView.post` \| branch \| bad credentials \| authentication failed \| \| `LoginView.post` \| exit \| success \| login success, user_pk= \| ``` Beats vocabulary: `entry \| config \| validation \| processing \| branch \| exit \| error`. Do not cite dropped rule `add-logging`. Mandatory Section F — MCP Tools to Expose (skip with "Not applicable" if MCP not in scope): ``` ## MCP Tools to Expose \| Tool name \| Service method \| Write? \| HITL? \| Auth injection \| \|-----------\|---------------\|--------\|-------\|----------------\| \| `create_foo` \| `FooService.create` \| Yes \| No \| server-side user_id \| ``` Rules: artifact 57 §3.2 (tool schema), §3.3 (auth injection — never accept user_id from args), §3.4 (write-tool policy) Mandatory Section G — Agent proofs (skip with "Not applicable" if SAO §17 is N/A or this feature does not touch agent capabilities): ``` ## Agent Proof Table \| PRF ID \| Workflow \| Script path \| Trace beats to assert \| Adverse? \| \|--------\|----------\|-------------\|----------------------\|----------\| \| PRF-SC01-04 \| munin_chat \| tests/fixtures/llm_scripts/PRF-SC01-04/happy.json \| tools_blocked: list_entities \| yes \| ``` Rules: - Map only PRF rows from SAO §17 / DTA-19 §13 that this feature affects. - Script paths under `tests/fixtures/llm_scripts/<prf-id>/` (`happy.json`, `reject_.json`). - Section D must name matching `test__agent_story_` tests for every selected PRF row. - TASK- golden tasks (lane 4) belong in SAO §17 / nightly eval — list in plan only when this slice introduces or changes a golden task fixture. - Reference: artifact 56 Part 4.5, skill Agent Integration Proof Patterns, rule `do-assert-agent-story`. Implementation Steps: 1. Backend Implementation: models, admin, services, views, URLs. Follow the Rules section below. 6. MCP Tool Registration (if SAO §18 in scope): - Declare the tool in `mcp/tools/` wrapping the service method; apply server-side auth injection. - Register with `initialize_mcp()`. - Apply stdout hygiene if stdio transport (artifact 57 §6). - Reference: artifact 57 §3–§4 7. ToolExecutor Wiring (if SAO §17 in scope): - Register the service callable in `ToolExecutor` under the tool name expected by the agent loop. - Ensure the return envelope matches the stable format. - Mark as HITL if destructive. - Reference: artifact 56 §4.3 2. Frontend Implementation: Django templates, HTMX, partials, `data-testid` attributes. 3. Testing — prove what's working: behavior tests red → green → refactor. Unit, integration (no mocks), view tests. Then log-story tests red → green in the same slice (caplog / `assert_log_story`). When Section G has rows: agent-proof tests red → green in the same slice (`@agent_proof` / `assert_agent_story` / CAP-004 ScriptedLLM). MCP tools (if Section F populated): Tests to Create table must include T1 + T2 per new tool; T3 required if stdio: - T1 (FastMCP Client): `async with Client(transport=mcp) as c: await c.call_tool(...)` — proves schema, registration - T2 (Direct service): call service with real DB — proves service/ORM wiring - T3 (subprocess JSON-RPC): proves entrypoint cleanliness (no stdout noise) - Full recipes: artifact 57 §7 4. Observability: emit INFO at decision points matching the Log Story Script (who/what/when/why, never raw secrets). Prove with caplog tests — ban deferred "informative logging pass" slices. 5. Commit Strategy: Angular convention after every principal step. Behavior + log-story (+ agent-proof when Section G populated) green in the same commit. When GitHub issue #N will hand off this plan: list one commit per implementation slice in the plan; first commit is plan/docs handoff only (`docs(plan): … Refs #N`); slice commits use `Refs #N`; final slice uses `Closes #N`. Each slice requires `gh issue comment N` with commit SHA (rule `do-github-issues`). ### Steps 7–10: Rule Confirmation, No Time Estimates, Submit for Approval, GitHub Issue Issue body must contain all seven mandatory sections inline (A–G, not linked). Each section must be self-sufficient for a cold-start implementor. When used under PIN, note that `checkpoint.log_story_command` and `checkpoint.agent_proof_command` (when Section G populated) must pass alongside the behavior checkpoint. ### Step 7: Write Lessons Learned Before creating the GitHub issue, add a `## Lessons Learned` section to the issue body. The question is open-ended: Completing this story — what difficulties did you encounter? How could the task definition, tools, and artifacts you received have been improved to make accomplishing this task easier, without creating extra duplicates or contradictions elsewhere? This is not a finite list of categories. Write freely. If something matters, write it down. Areas that often surface signal (use them if they apply, ignore if they don't): - Missing or unclear artifacts (mockups, SAO sections, feature files, skills) - Activity steps that contradicted each other, the feature spec, or `user_journey.md` - Technical decisions made during planning not yet in `docs/architecture/SAO.md` - Deviations from the written BDD scenarios (scope narrowed, step reworded, constraint added) If nothing to note: `## Lessons Learned — None.` One honest sentence beats four empty bullet points. The reader is MIN-05 closing the iteration and PIN-02 opening the next one. ### Step 8: GitHub Issue Handoff (hard gate — blocks BPE-02 / MIN-04 code) After user approves the plan and before any implementation slice (including spec/Gherkin): 1. Create GitHub issue #N — body inlines sections A–G + `## Lessons Learned` placeholder + checkpoint YAML when used under PIN. 2. Update plan INDEX with issue #N and plan link. 3. Commit docs/plan only: `docs(plan): {wave} plan and GitHub issue #N` with footer `Refs #N`. 4. Post issue comment citing handoff commit SHA and listing slice order from the plan. Do not modify `src/`, `tests/` implementation, or production templates until step 3 is committed and step 4 is posted. ## Rules Before planning and writing the implementation plan, read each Rule below in this playbook (by slug), then apply it when filling Mandatory Sections D–G and the Implementation Steps. Do not rely on memory of the rule text. Required: - `do-plan-before-doing` - `do-skeletons-first` - `do-test-first` - `do-not-mock-in-integration-tests` - `do-informative-logging` - `do-assert-log-story` - `do-assert-agent-story` (when SAO §17 in scope) - `do-write-concise-methods` - `do-docstring-format` - `do-semantic-versioning-on-ui-elements` - `do-follow-commit-convention` - `do-small-increments` - `pytest` - `do-github-issues` Activity-specific (not a substitute for the rules above): - Mandatory Section E is a Log Story Script (Where / Beat / Trigger / Must include); Section D must name matching `_log_story_` tests when Section E is non-empty. - Mandatory Section G is an Agent Proof Table when SAO §17 applies; Section D must name matching `_agent_story_` tests when Section G is non-empty. - Logging and agent proofs ship in the same green slice as behavior — ban deferred logging or agent-testing passes. ## Success Criteria - Feature specification exists and is clear - Codebase assessment complete with context map (3–5 file:line_range references) - Plan contains all seven mandatory sections: Context Map, Do-Not-Do, SAO Sections, Tests to Create, Log Story Script, MCP Tools to Expose, Agent proofs (or explicit N/A for G) - All tests explicitly listed with what they prove, including `_log_story_` when Section E has rows and `_agent_story_` when Section G has rows - All log decision points listed with Beat + required context fields - When SAO §17 in scope: PRF rows mapped with script paths and trace beats; Section D lists agent_story tests - If MCP tools added: Tests to Create table contains T1+T2 rows per new tool (T3 if stdio) - Plan reviewed and approved by user - GitHub issue created/updated with all mandatory sections inline - `## Lessons Learned` section present in the issue body - Handoff commit `docs(plan): … Refs #N` exists before any implementation commit for this feature - Plan lists slice commit boundaries; issue #N created with A–G inline before BPE-02
Implement Backend	BPE-2	Build Feature	Junior Edda	Construction (#3)	Read the 'BPE-2 Implement Backend' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Implement backend services, models, and views following test-first development and small increments approach. ## Steps ### 1. Create Skeletons Create all class and method skeletons with full docstrings following your language's documentation conventions. The core principle: the developer who has no knowledge of the system can implement methods/properties etc. following only documentation in the skeleton. - Create class and method/function stubs and document them - Include full docstrings, return types, and sample return values - Use appropriate placeholder (e.g., `NotImplementedError`, `TODO`, `panic!`, etc.) - Do not skip type hints or documentation - Add comments inside the methods pointing attention to the logic flow, exception handling, logging etc. ### 2. Write Behavior Tests Before Logic Write unit tests before writing method logic using your test framework. Use real dependencies in integration scenarios - no mocking. ### 3. Implement Incrementally (behavior green) Work method-by-method. Each method/property should be: implemented → behavior-tested → log-story tested (step 4) → agent-proof tested (step 4b when declared) → committed. ### 4. Log Story — Caplog in the Same Slice For each footprint method covered by the plan's Log Story Script: 1. Write `test__log_story_happy` and/or `test__log_story_reject` (red) 2. Emit INFO logs that satisfy story beats (`entry → config → validation → processing → branch → exit → error`) per `do-informative-logging` 3. Make log-story tests green using skill Pytest Log Story Assertions (`tests/support/log_story.py` → `assert_log_story`) once TFK-02 has bootstrapped the helper — per `do-assert-log-story` 4. Never defer logging to a later "informative logging pass" slice ### 4b. Agent Proof — Same Slice (when SAO §17 / plan Section G in scope) For each PRF row in the plan's Agent Proof Table: 1. Write `test__agent_story_happy` and/or `test__agent_story_reject` marked `@pytest.mark.agent_proof` (red) 2. Queue ordered LLM scripts from `tests/fixtures/llm_scripts/<prf-id>/` via CAP-004 ScriptedLLM — only the LLM may be scripted; real DB, real tool registry 3. Make agent-story tests green using skill Agent Integration Proof Patterns (`tests/support/agent_story.py` → `assert_agent_story(...)`) per `do-assert-agent-story` 4. Assert control-plane trace beats (workflow, tools offered/called, domain effects, blackboard/plan state) — not assistant prose 5. Never defer agent proofs to a later "agent testing pass" slice ### 5. Commit After Each Step Write → run → test (behavior + log story + agent proof when declared) → evaluate → fix. Commit using Angular-style commit messages. Behavior, log-story, and agent-proof green in the same commit when declared. Issue #N (when active): footer `Refs #N` on every slice commit; immediately `gh issue comment N` with `` `{short-sha}` ``, slice summary, next slice. Do not start the next plan slice until both are done. See rule `do-github-issues`. ### 6. Backend Architecture - Services Layer: Business logic shared between different interfaces (API, Web UI, CLI, etc.) - Repository Pattern: Data access abstraction (can be swapped) - Views/Controllers: Return appropriate responses for your framework - API Endpoints: Follow RESTful or your framework's conventions - Context/State: Always validate and document ### 7. Route Registration Register new routes/endpoints with descriptive names. Follow your framework's conventions for URL/route structure. ### 8. Testing Views/Controllers Use your framework's test client. Test responses, validate context/state, check templates/views used, test dynamic endpoints. Include caplog assertions for Log Story Script rows on those views. ### 9. Scan Skills Query Playbook Skills where `capability_domain` in: - `BACKEND_FRAMEWORK` — Backend implementation patterns for your tech stack - `TEST_FRAMEWORK` — Testing patterns and best practices - `LOGGING_PATTERN` — Logging implementation for your language - `LOG_STORY_TESTING` — Pytest Log Story Assertions / caplog helpers - `AGENT_PROOF_TESTING` — Agent Integration Proof Patterns / agent_story helpers - `DOCSTRING_FORMAT` — Documentation format for your language Apply reference implementations and patterns from matched Skills. ## Rules Before implementing, read each Rule below in this playbook (by slug), then apply it to every change in this activity's footprint. Do not rely on memory of the rule text; do not paraphrase the rule body into this activity. Required: - `do-skeletons-first` - `do-test-first` - `do-not-mock-in-integration-tests` - `do-informative-logging` - `do-assert-log-story` - `do-assert-agent-story` (when plan Section G / SAO §17 PRF rows in scope) - `do-import-on-module-level` - `do-write-concise-methods` - `do-docstring-format` - `do-follow-commit-convention` - `do-small-increments` - `pytest` - `do-github-issues` Activity-specific (not a substitute for the rules above): - Log-story tests (`_log_story_` / caplog) ship in the same red→green slice as behavior — no deferred logging pass. - Agent-proof tests (`_agent_story_` / `@agent_proof`) ship in the same red→green slice as behavior when Section G declares PRF rows — no deferred agent-testing pass. ## Success Criteria - All skeletons created with full documentation - Behavior tests written before implementation and passing - Log Story Script rows proven by passing `_log_story_` caplog tests in the same commit as behavior - Agent Proof Table rows proven by passing `_agent_story_` tests in the same commit as behavior (when Section G populated) - No deferred logging or agent-proof slice in the plan - Code committed with proper messages - Every slice commit for issue #N referenced in a GitHub issue comment with SHA - Routes/endpoints properly registered - Services layer properly structured
Implement Frontend	BPE-3	Build Feature	Junior Edda	Construction (#3)	Read the 'BPE-3 Implement Frontend' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Implement frontend templates and interactions following your framework's patterns with appropriate rendering approach. ## Prerequisites - Backend implementation completed with passing tests - Routing defined - Review UX/design guidelines to identify sections applicable to the page/component ## Steps ### 1. Review Routing and Template Structure Check routing patterns - does anything need to be added or changed? Plan template/component hierarchy (base templates, partials, pages/components). Identify dynamic interactions needed. ### 2. Implement Templates/Components A. Page Templates/Components: Full pages (inherit from base or layout) B. Partials/Components: Reusable fragments for dynamic updates C. Dynamic Attributes: Use your framework's patterns for interactions D. Forms: Forms with appropriate validation and submission handling E. Visualizations: Embed visualizations as appropriate for your stack Add test IDs (`data-testid` or equivalent) to all interactive elements. Work in small increments. ### 3. Interaction Patterns - Navigation: Follow your framework's navigation patterns - Forms: Handle submission with validation feedback - Dynamic Lists: Refresh/update lists dynamically - Modals/Dialogs: Implement dialogs with dynamic content loading Add minimal client-side code only for: * Framework-specific enhancements * Client-side validation enhancement * Interactive effects (tooltips, hover, etc.) ### 4. Development Testing Start your development server Test in browser Check console for errors Verify forms submit correctly Test visualizations render properly Validate dynamic updates work as expected ### 5. Add Semantic Test IDs Add `data-testid` attributes using kebab-case. Use semantic names that describe purpose, not structure. Required on: buttons, links, form inputs, containers, error messages. ### 6. Styling Read `docs/ux/IA_guidelines.md` to identify what applies to the page/component and apply them. Use simple CSS, keep styles in static/css/, use semantic HTML elements, ensure responsive design. ### 7. Commit Changes Commit frontend changes using Angular-style commit messages. ### 8. Integration Validation Verify all views/controllers return correct templates/components, check dynamic interactions update correct elements, ensure forms handle validation errors properly, test visualizations render correctly, validate test IDs are present for testing. ### 9. Scan Skills Query Playbook Skills where `capability_domain` in: - `FRONTEND_FRAMEWORK` — Frontend implementation patterns for your tech stack - `UI_TESTING` — UI testing patterns and semantic naming conventions Apply reference implementations and patterns from matched Skills. ## Rules to Follow ### I. Semantic Naming for UI Elements Test Selector Hierarchy: 1. Test IDs (`data-testid` or framework equivalent) - Primary choice for all components 2. Semantic attributes (`aria-label`, role) - Secondary for semantic elements 3. Label association - For form inputs 4. Text content - Only for static, stable content 5. Avoid CSS selectors or XPath when possible Every interactive element MUST have: - Proper test ID attribute - `aria-label` or descriptive text for buttons - Associated label elements for form inputs - Unique accessible names for dialogs Hierarchical Test ID Naming: - Page-Level: `{domain}-page` - Feature Components: `{domain}-card` - Action Elements: `{action}-{domain}-button` - Form Elements: `{domain}-{field}-input` - Status/Feedback: `{type}-message` ### II. Small Increments Work in small vertical slices. After every change: write → run → test → evaluate → fix. No large PRs or 1000-line commits. ### III. UI Design Rules Action Buttons and Links: - Every action button/link should have an appropriate icon - If no icon specified in requirements, propose 3 icon options for user to choose - Icons should be semantically appropriate for the action Tooltips/Help Text: - Every action button should have helpful tooltip or help text - Active buttons: Explain clearly what will happen when clicked - Disabled buttons: Explain why it's disabled and what needs to be done to enable it - Use your framework's tooltip/help text patterns - Keep text concise but informative ### IV. Validation Checklist Before committing any component, verify all interactive elements have proper attributes and accessibility features. ## Success Criteria - All templates/components implemented with semantic markup - Dynamic interactions working as expected - All interactive elements have test ID attributes - Forms handle validation errors properly - Responsive design verified - Code committed with proper messages ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - User Journey (Document, Required) — produced by Define User Journey (#36). - IA Guidelines (Document, Required) — produced by Define Information Architecture (#37). - 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). - System Architecture Overview Template (Template, Required) — produced by Write SAO.md (#59). - Implementation Plan Template (Template, Required) — produced by Plan Feature (#96). - Definition of Done Checklist Template (Template, Required) — produced by Check Definition of Done (#101).
Implement Feature Acceptance Tests	BPE-4	Build Feature	Junior Edda	Construction (#3)	Read the 'BPE-4 Implement Feature Acceptance Tests' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. APPEND TO GUIDANCE: --- ## TFK Integration: Behave-Based Acceptance Tests Feature acceptance tests are executed via behave-django against `.feature` files in `docs/features/` (spec + AT runner — single source of truth). There is no separate `tests/acceptance/` tree and no promote/copy step. ### Updated Process 1. Locate spec: Find the feature's BDD scenarios in `docs/features/act-/`. 2. Verify steps exist: Check that all steps used in the spec have implementations in `docs/features/steps/`. If any are missing, invoke TFK-07. 3. Remove `@wip` when ready: Tag unimplemented scenarios `@wip` during ESM; remove the tag when implementation is complete so CI runs them (`behave.ini` uses `tags = ~@wip`). 4. Prepare fixtures: Check the Fixture Library Catalog for needed test data. If presets are missing, invoke TFK-07. 5. Run acceptance tests: `make test-at` (runs `docs/features/` via `behave.ini`). 6. The dual approach remains: Django test client unit/integration tests remain valuable for fast feedback. Behave AT runs the same scenarios through the BDD layer. Both must pass. ### Key Principle Acceptance tests are the real thing minus the GUI (Django test client — not Playwright). No mocking. The `.feature` file in `docs/features/` IS the grounding executable requirements document for AT. ## Skills (additional) - Behave-Django BDD Runner* (BDD_RUNNER) ## Inputs (additional) - Step Library Catalog (Document, Required) — produced by TFK-03. - Fixture Library Catalog (Document, Required) — produced by TFK-04. - Behave Configuration (Code, Required) — produced by TFK-02 (Artifact #51). --- ## TFK Integration: Behave-Based Acceptance Tests Feature acceptance tests are executed via behave-django against `.feature` files in `docs/features/` (spec + AT runner — single source of truth). There is no separate `tests/acceptance/` tree and no promote/copy step. ### Updated Process 1. Locate spec: Find the feature's BDD scenarios in `docs/features/act-/`. 2. Verify steps exist: Check that all steps used in the spec have implementations in `docs/features/steps/`. If any are missing, invoke TFK-07. 3. Remove `@wip` when ready: Tag unimplemented scenarios `@wip` during ESM; remove the tag when implementation is complete so CI runs them (`behave.ini` uses `tags = ~@wip`). 4. Prepare fixtures: Check the Fixture Library Catalog for needed test data. If presets are missing, invoke TFK-07. 5. Run acceptance tests: `make test-at` (runs `docs/features/` via `behave.ini`). 6. The dual approach remains: Django test client unit/integration tests remain valuable for fast feedback. Behave AT runs the same scenarios through the BDD layer. Both must pass. ### Key Principle Acceptance tests are the real thing minus the GUI (Django test client — not Playwright). No mocking. The `.feature` file in `docs/features/` IS the grounding executable requirements document for AT. ## TFK boundary: AT (user-visible) vs `@agent_proof` pytest Do not* express agent orchestration proofs as Behave scenarios. \| Concern \| Layer \| Runner \| Marker / location \| \|---------\|-------\|--------\|-------------------\| \| User-visible behavior, screens, HTMX, API responses humans see \| AT \| behave-django (`make test-at`) \| `.feature` in `docs/features/` \| \| Agent control-plane wiring (PRF-): tool allowlists, blackboard, plan handoff, HITL gates, 429 retry \| Integration \| pytest `@pytest.mark.agent_proof` \| `tests/integration/agent/` \| \| Deterministic shell (lane 2): D0 pre-filter, JSON parse, validate-before-LLM \| Integration \| pytest (no `@agent_proof`) \| `tests/integration/` \| \| Model quality / golden tasks (TASK-, lane 4) \| Eval \| pytest `@pytest.mark.quality` + `@pytest.mark.live_llm` \| `tests/fixtures/agent_tasks/` — nightly, not AT \| Rules: - AT proves what the user sees — forms, redirects, ChangeSet approval UI, error messages. - `@agent_proof` proves what the agent loop did under CAP-004 ScriptedLLM — trace beats via `assert_agent_story`, not chat prose assertions in Gherkin. - When a feature touches both surfaces, BPE-04 adds/updates `.feature` scenarios and BPE-02 (or the agent slice) adds `@agent_proof` tests — both green before DoD; neither substitutes for the other. - Skip `@agent_proof` rows in BPE-04 when SAO §17 is N/A. ## Skills (additional) - Behave-Django BDD Runner (BDD_RUNNER) - Agent Integration Proof Patterns (TEST_INTEGRATION) — when SAO §17 in scope; AT does not replace this skill ## Inputs (additional) - Step Library Catalog (Document, Required) — produced by TFK-03. - Fixture Library Catalog (Document, Required) — produced by TFK-04. - Behave Configuration (Code, Required) — produced by TFK-02 (Artifact #51). - Agent Proof Table (from BPE-01 Section G, when SAO §17) — PRF rows map to pytest, not `.feature` files.
Implement Journey Certification Tests	BPE-5	Build Feature	Junior Edda	Construction (#3)	Read the 'BPE-5 Implement Journey Certification Tests' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. APPEND TO GUIDANCE: --- ## TFK Integration: E2E Infrastructure Journey certification tests that require browser-based Playwright execution use TFK's E2E infrastructure under `tests/e2e/`. ### E2E vs AT (clarification) - AT (BPE-04): Proves one particular feature works. `docs/features/` via Django test client (`behave --simple`). Fast. Every CI run. - E2E (BPE-05): Proves the ability to fulfill a goal using system means. `tests/e2e/` via Playwright + LiveServer. Sequential. Screenshots. Staging / release certification. Same Gherkin phrases (catalog); separate step implementations and `environment.py`. ### Using TFK E2E Infrastructure 1. Locate journey intent: Read `docs/features/user_journey.md` for the multi-screen goal. 2. Write E2E `.feature`: Add journey scenarios to `tests/e2e/` (optionally tag `@e2e`). 3. Write as multi-phase .feature: One long sequential `.feature` file with multiple scenarios. 4. Environment targeting: Use `--base-url` to point at any environment. 5. Screenshots: `tests/e2e/environment.py` automatically captures screenshots after every step. 6. Data preparation: E2E tests use `--db-uri` to load initial data via loaddump. 7. Run: `make test-e2e` → `manage.py behave tests/e2e/`. ## Inputs (additional) - E2E Test Configuration (Code, Required) — produced by TFK-06. - Fixture Library Catalog (Document, Required) — produced by TFK-04. --- ## TFK Integration: E2E Infrastructure Journey certification tests that require browser-based Playwright execution use TFK's E2E infrastructure under `tests/e2e/`. ### E2E vs AT (clarification) - AT (BPE-04): Proves one particular feature works. `docs/features/` via Django test client (`behave --simple`). Fast. Every CI run. - E2E (BPE-05): Proves the ability to fulfill a goal using system means. `tests/e2e/` via Playwright + LiveServer. Sequential. Screenshots. Staging / release certification. Same Gherkin phrases (catalog); separate step implementations and `environment.py`. ### Using TFK E2E Infrastructure 1. Locate journey intent: Read `docs/features/user_journey.md` for the multi-screen goal. 2. Write E2E `.feature`: Add journey scenarios to `tests/e2e/` (optionally tag `@e2e`). 3. Write as multi-phase .feature: One long sequential `.feature` file with multiple scenarios. 4. Environment targeting: Use `--base-url` to point at any environment. 5. Screenshots: `tests/e2e/environment.py` automatically captures screenshots after every step. 6. Data preparation: E2E tests use `--db-uri` to load initial data via loaddump. 7. Run: `make test-e2e` → `manage.py behave tests/e2e/`. ## Inputs (additional) - E2E Test Configuration (Code, Required) — produced by TFK-06. - Fixture Library Catalog (Document, Required) — produced by TFK-04. --- ## Responsive Viewport Certification Use the viewport matrix and Screen ID-to-recipe coverage table from `docs/ux/IA_guidelines.md` as executable test input. 1. Parameterize Playwright browser contexts with every required CSS-pixel viewport profile. 2. Exercise each journey screen at every profile. Shared recipe assertions may be reused across screens, but the coverage report must show every Screen ID/profile pair. 3. Assert the universal IA outcomes: no unintended page-level horizontal overflow; no clipped or overlapping essential content; coherent stacking and focus order; reachable navigation and primary action; intentional overflow contained by its component; and correct low-height or full-viewport behavior. 4. Add focused assertions for every screen-specific responsive scenario from ESM-05. 5. Capture a screenshot after the responsive layout has settled at each Screen ID/profile pair. Mask or stabilize volatile content according to the test architecture. 6. Produce a responsive evidence manifest containing Screen ID, recipe, profile, viewport dimensions, assertion result, and screenshot path. Do not certify responsiveness from a single default browser context. A screenshot alone is review evidence, not a substitute for layout assertions; assertions alone are not a substitute for human visual review of the required evidence set.
Check Definition of Done	BPE-6	Build Feature	Junior Edda	Construction (#3)	Read the 'BPE-6 Check Definition of Done' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Validate that feature/story implementation complies with all project rules and standards by examining current state and outputs. ## Core Development Rules Checklist ### Test-First Development - [ ] Every function/method has corresponding test(s) - [ ] Feature files in `docs/features/` exist and comply with scenarios - [ ] Tests use pytest framework - [ ] Mocking is minimal ### Continuous Testing - [ ] All tests are runnable via `pytest tests/` - [ ] Tests are pytest compatible with proper fixtures - [ ] `tests.log` file exists and contains test output ### Concise Methods - [ ] Top-level (public) methods are 20-30 lines maximum - [ ] Supporting logic is in well-named private methods - [ ] Helper methods have single, focused responsibilities - [ ] Method names are descriptive and clear ## Code Quality Rules Checklist ### Import Management - [ ] All imports are at module level - [ ] No imports inside functions/methods - [ ] Dependencies are properly declared ### Log Story Verification - [ ] Implementation plan / issue contains a Log Story Script (Where / Beat / Trigger / Must include) - [ ] Every script row is proven by a passing `_log_story_` caplog test (or `checkpoint.log_story_command` from the iteration manifest) - [ ] Happy and reject paths covered when the scenario has both - [ ] Log levels are appropriate (DEBUG, INFO, WARNING, ERROR) - [ ] No secrets/tokens/passwords appear at INFO in asserted lines - [ ] No deferred logging slice remains in the plan Grep of `logs/app.log` is an audit aid, not the DoD gate. Caplog (or `log_story_command`) is the gate. ### Agent Proof Verification (when SAO §17 / plan Section G in scope) - [ ] Implementation plan / issue contains an Agent Proof Table (PRF ID, workflow, script path, trace beats) - [ ] Every PRF row is proven by a passing `_agent_story_` test marked `@pytest.mark.agent_proof` (or `checkpoint.agent_proof_command` from the iteration manifest) - [ ] Happy and reject paths covered when the PRF is adverse or has a reject sketch - [ ] Tests use CAP-004 ScriptedLLM only — no `FakeLLM`, no `@patch` on ToolExecutor or domain services in `@agent_proof` tests - [ ] LLM scripts exist under `tests/fixtures/llm_scripts/<prf-id>/` for every asserted path - [ ] Trace asserts control-plane beats (tools, domain writes, plan/blackboard state) — not assistant wording - [ ] No secrets/tokens/passwords in trace or asserted log lines - [ ] No deferred agent-proof slice remains in the plan - [ ] TASK-* lane 4 evals (if any) are not required for story DoD — confirm they remain on nightly/promotion band only Grep of run logs is an audit aid, not the DoD gate. `assert_agent_story` (or `agent_proof_command`) is the gate. ## Testing and Quality Assurance Checklist ### Integration Test Standards - [ ] Integration tests in `tests/integration/` exist - [ ] Integration tests avoid mocking (except CAP-004 ScriptedLLM in `@agent_proof` tests) - [ ] Real dependencies are used in integration scenarios ### Commit Conventions - [ ] Recent commit messages follow Angular conventional format - [ ] Commits are atomic and focused - [ ] Breaking changes are documented in commit messages ## UI and Frontend Rules Checklist ### Django Views + HTMX - [ ] No DRF views exist for new web UI features - [ ] Django views return HTML templates - [ ] HTMX attributes used for dynamic interactions - [ ] Services layer is shared between MCP and Web UI ### Semantic Naming - [ ] All interactive elements have `data-testid` attributes - [ ] Naming follows kebab-case convention - [ ] Form inputs have proper name and id attributes ## Documentation Checklist ### Scenario Writing - [ ] BDD scenarios exist for features - [ ] Feature files are well-structured - [ ] Scenarios cover edge cases and error conditions - [ ] Review GUI - do scenarios match behavior, fields, URLs, design rules? Report inconsistencies to user ### TODO Management - [ ] TODO comments exist for incomplete implementations - [ ] TODO items have clear descriptions - [ ] TODOs in dependencies can be ignored ### Document Updates - [ ] Review code: new packages, patterns, approaches worth documenting? - [ ] Review conversation: need to update feature files/corrections? - [ ] Review modus operandi against workflows and rules - can we improve? ## Final Validation Checklist ### Overall Quality Check - [ ] Feature meets acceptance criteria - [ ] Code is production-ready - [ ] Documentation exists and is accurate ### Integration Validation - [ ] Feature integrates with existing system - [ ] No breaking changes introduced - [ ] Dependencies properly declared in requirements.txt ### Deployment Readiness - [ ] Database migrations exist if needed - [ ] Environment variables are documented - [ ] Configuration changes are documented ### Cleanup - [ ] Remove temporary files like debug_.py - [ ] Scan file structure for stray misplaced files - [ ] Remove .log files from repository ## Rules Before validating DoD, read each Rule below in this playbook (by slug), then apply it as the acceptance criterion for the matching checklist items. Do not rely on memory of the rule text. Required: - `do-test-first` - `do-continuous-testing` - `do-write-concise-methods` - `do-import-on-module-level` - `do-informative-logging` - `do-assert-log-story` - `do-assert-agent-story` (when SAO §17 / Section G in scope) - `do-not-mock-in-integration-tests` - `do-follow-commit-convention` - `do-semantic-versioning-on-ui-elements` - `do-write-scenarios` - `do-add-todos-for-incomplete-items` - `pytest` Activity-specific (not a substitute for the rules above): - Observability DoD is Log Story Verification (caplog / `log_story_command`), not "logging statements exist". - Agent DoD is Agent Proof Verification (`agent_proof_command` / `@agent_proof`), not "the agent loop exists" or Behave AT alone. ## Actions All checkboxes must be completed before considering the story "Done". Any deviations must be presented to user. If user says "collect for cleanup but defer" - create a Backlog item in GitHub as Issue with "deferred" tag. Otherwise resolve deviations as directed by user, commit following Angular convention, and send Pull Request. ## Success Criteria - All checklist items verified - No deviations or all approved by user - Code production-ready - Ready for PR ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - Feature Files (Document, Required) — produced by Write Feature Files (#39). - Implementation Plan Template (Template, Required) — produced by Plan Feature (#96). ## Defects Found During DoD When DoD review reveals a defect (behavior does not match feature files or acceptance criteria) — not a deferred cleanup item: 1. File a Bug Report via `report_bug` MCP tool or Feedback UI (see Bug Report artifact for body structure) 2. Invoke Fix Bug (BPE-09) with the Bug Report as input 3. Do not mark the story done until blockers are resolved and BPE-09 success criteria are met --- ## Responsive Coverage Verification For every story that adds or changes a user-visible screen: - [ ] The Screen ID maps to a named responsive page-layout recipe in the IA coverage table. - [ ] Any deviation from the shared recipe is documented in the IA and covered by focused ESM-05 scenarios. - [ ] ESM-06 mockup evidence exists for every required viewport, or the implementation plan records why an approved existing recipe is the authoritative mockup reference. - [ ] BPE-05 responsive assertions pass for every required viewport profile. - [ ] The responsive evidence manifest contains every affected Screen ID/profile pair and links its screenshots. - [ ] Human visual review confirms no clipping, overlap, inaccessible actions, broken reading/focus order, or unintended page-level horizontal scrolling. - [ ] Intentional table/component overflow is local to the documented wrapper. - [ ] Wide but low-height profiles preserve primary-action reachability and documented scrolling/full-viewport behavior. Do not mark the story Done when any required profile is missing, failed, or unreviewed. Record and resolve mismatches through the normal defect path; do not silently weaken the viewport matrix or page recipe.
Finalize Feature	BPE-7	Build Feature	Junior Edda	Construction (#3)	Read the 'BPE-7 Finalize Feature' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Finalize feature with testing, validation, and deployment preparation. ## Steps ### 0. Run All Tests Run all tests and ensure none are broken. If there are discrepancies between test expectations and implementation - ask user to clarify what takes precedence. Mark scenarios with "done" emoji and add "completed" tag. ### 1. Identify E2E Test Identify Playwright E2E test for this feature/scenario. If there is none - ask user if they want to create one. ### 2. Run Development Server and Validate Auto-run: Start the server: `python manage.py runserver` Execute Playwright tests to ensure they pass. Fix any issues found during testing. ### 3. Run Full Test Suite Auto-run: Execute all unit tests, integration tests, and E2E tests. Ensure no regressions were introduced. Fix any failing tests. ### 4. Update Project Dependencies Add any new packages to requirements.txt that were added during feature development. Use `pip install <package>` to add new dependencies. Ensure version constraints are appropriate. Test that `pip install -r requirements.txt` works in a fresh venv. ### 5. Present Completed Work Summarize implemented features and changes. Show test results and coverage. Demonstrate functionality if possible. ### 6. Final Commit Check if there is a corresponding issue. Update the status with the latest changes and associate commit. Commit all remaining changes using Angular-style commit messages. Ensure commit message clearly describes the completed feature. ### 7. Handle Feature Branch If on feature branch - ask user if they want to send a PR or merge into main. ### 8. Update Screen Flow Diagram Update `docs/ux/2_dialogue-maps/screen-flow.drawio` to mark completed screens with green borders: - Change `strokeColor=#1565c0` to `strokeColor=#22c55e` (green) - Add `strokeWidth=3` if not present - Add ✅ emoji prefix to screen labels - This indicates feature completion per the diagram legend ### 9. Close and Mark Complete Close issue if exists, review and mark all todos as "done" in the implementation plan, and update scenario and/or feature with "done" emoji. ## Rules to Follow ### I. 100% Test Pass Rate Required Only 100% test pass rate can be reported as "success" or "complete". 92%, 95%, 99% are NOT success. Any failing tests must be fixed before declaring feature complete. Cannot mark features as "done" or "production-ready" with failing tests. Test failures must be resolved, not deferred or ignored. Exception: Only if user explicitly approves deferring specific test scenarios can they be excluded from the count. ### II. Fix Tests Immediately Failing tests are major problem - we don't start new development until we fix them. ### III. Commit Convention Follow Angular convention with proper type, scope, subject, body, and footer. ## Success Criteria - All tests passing (100% pass rate) - Dependencies updated in requirements.txt - Final commit made with clear message - Issue updated and closed - Implementation plan marked complete - Feature file updated with completion markers ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - Screen Flow / Dialogue Map (Diagram, Optional) — produced by Create Dialogue Maps (#38). - Implementation Plan Template (Template, Required) — produced by Plan Feature (#96). - Definition of Done Checklist Template (Template, Required) — produced by Check Definition of Done (#101). ## Defects Found During Finalization When testing or validation reveals a defect (failing test that exposes a real bug, user-reported issue during demo, or ERROR in `logs/app.log` tied to broken behavior): 1. File a Bug Report via `report_bug` MCP tool or Feedback UI (see Bug Report artifact for body structure) 2. Invoke Fix Bug (BPE-09) — do not patch ad hoc without the test-first workflow 3. Do not declare the feature complete until BPE-09 success criteria are met (100% regression green)
Process Change Request	BPE-8	Build Feature	Junior Edda	Construction (#3)	Read the 'BPE-8 Process Change Request' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Process an enhancement or change request by reconciling requirements across the spec stack, agreeing a target state with the user, then closing with an approved reconciliation record and in-place spec updates. This activity does not implement code. ## Requirements Sources Reconcile across all layers that exist in this project. Read what is present; skip absent layers and note the gap in the matrix. For each affected Screen ID, build a reconciliation matrix: \| Layer \| Typical source \| Activity \| Current state \| Drift? \| Notes \| \|-------\|----------------\|----------\|---------------\|--------\|-------\| \| User journey \| User Journey document \| Define User Journey \| — \| Y/N \| Screen narrative \| \| Scenarios \| Feature files (Gherkin) \| Write Feature Files \| — \| Y/N \| Executable requirements \| \| Mockups \| HTML mockups / prototypes \| Create Mockups \| — \| Y/N \| UX validation screens \| \| Screen flow \| Dialogue map \| Create Dialogue Maps \| — \| Y/N \| Navigation flow \| \| IA guidelines \| IA guidelines \| Define Information Architecture \| — \| Y/N \| Design system rules \| \| Prior plan \| Implementation plan \| Plan Feature \| — \| Y/N \| What was planned \| \| Architecture \| SAO.md \| Write SAO.md \| — \| Y/N \| As-designed constraints \| \| As-built \| Code, templates, tests \| BPE-02–07 \| — \| Y/N \| What shipped \| ## Steps ### 1. Reconcile Requirements (read-only first) - Read inputs per ## Inputs below - Read the change request thoroughly; identify affected Screen IDs and scope - Read user journey — locate affected screen sections - Read feature files — locate affected scenarios - Read mockups — locate affected prototype screens - Read screen flow and IA guidelines when UI or navigation is in scope - Read SAO.md for architectural constraints touched by the change - Inspect as-built code and tests for the same Screen IDs - Flag conflicts between layers; do NOT assume — list open questions - If you don't understand user intent or UX details — ASK Fast path: If the matrix shows zero drift across all present spec layers and the change is purely cosmetic with no scenario impact, document the empty matrix and note minimal delta in the reconciliation document. ### 2. Propose Target State - Draft in-place revisions to canonical consumed artifacts (only layers where drift was found). Do not create parallel "Updated " copies — revise the same User Journey, Feature Files, Mockups, Screen Flow, and IA documents the project already uses. - Create Change Reconciliation Document* at `docs/plans/{FEAT}_CHANGE_RECONCILIATION.md` containing: - Trigger (change request summary) - Reconciliation matrix (from Step 1) - Proposed spec diffs (summary + file paths) - Open questions for user - Fast-path justification (if applicable) - Present target state to user; ask clarification questions - Gate: User must approve target state before closing this activity ### 3. Close Reconciliation - Ensure approved Change Reconciliation Document is saved at `docs/plans/{FEAT}_CHANGE_RECONCILIATION.md` - Ensure in-place revisions to canonical spec artifacts are complete (Step 2) - Technical replanning and implementation are out of scope for this activity — the human may invoke Plan Feature (Activity 96) separately when ready ## Rules to Follow ### I. Do Not Assume If unclear — ASK. Never guess user intent or implementation details. ### II. Spec Before Code Reconcile and update requirements artifacts before any implementation planning or coding. ### III. No Execution in Process Change Request Implementation, testing, and commits happen in later Build Feature activities after separate planning approval. ### IV. Traceability Every affected Screen ID must appear consistently across all present spec layers. Verify with project grep conventions. ## Success Criteria - Change request captured and understood - Reconciliation matrix complete for all affected Screen IDs - Canonical spec artifacts revised in place or explicitly marked unchanged (fast path) - Change Reconciliation Document created, saved, and user-approved - No code changes made during this activity ## 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). - IA Guidelines (Document, Optional) — produced by Define Information Architecture (#37). - System Architecture Overview Template (Document, Required) — produced by Write SAO.md (#59). - Implementation Plan Template (Template, Required) — produced by Plan Feature (#96). - Definition of Done Checklist Template (Template, Required) — produced by Check Definition of Done (#101).
Fix Bug	BPE-9	Build Feature	Junior Edda	Construction (#3)	Read the 'BPE-9 Fix Bug' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Fix a reported defect using a test-first workflow: prove the bug with a failing test, implement the fix, prove green, run full regression, then gate integration/PR/hotfix decisions with the user. This activity implements code. It does not reconcile requirements — use Process Change Request (#103) for scope or spec changes. ## Prerequisites - A Bug Report (GitHub Issue) filed via `report_bug` MCP tool or the Feedback UI - Bug may have been filed during Check Definition of Done (#101), Finalize Feature (#102), or Acceptance, Bug Reports & Deploy Fixes (#183) ## Steps ### 1. Analyze Why Tests Missed the Bug - Read the Bug Report thoroughly (Description, Reproduction, Environment, severity if present) - Identify affected feature files, scenarios, Screen IDs, and code paths - Determine why existing tests did not catch the defect — missing scenario, weak assertion, wrong test layer, integration gap, flaky test, etc. - Document the gap briefly (issue comment or working notes) ### 2. Add or Extend Tests (Red) - Write or extend tests that reproduce the bug — they must fail before the fix - Prefer the lowest appropriate layer per SAO Test Strategy: unit → integration → AT (`docs/features/`) → E2E (`tests/e2e/`) - Follow `do-test-first` and `do-not-mock-in-integration-tests` - Run the new or extended test(s) and confirm they fail for the expected reason ### 3. Implement the Fix - Implement the minimal correct fix - Keep scope focused — no unrelated refactors ### 4. Prove the Fix (Green) - Run the new or extended test(s) — must pass - If UI or journey behavior changed, re-run relevant BPE-04 / BPE-05 checkpoints for the affected scenario ### 5. Full Regression - Run the full test suite: `pytest tests/` - Run E2E suite when UI or journey paths changed: `pytest tests/e2e/` - 100% pass rate required before closing — same standard as Finalize Feature (#102) ### 6. Commit and User Gate - Commit with Angular convention: ```bash git add -A git commit -m "fix({scope}): {bug title}" ``` - Ask the user: 1. Integrate or submit PR? — merge to main locally, or open / submit a pull request? 2. Hotfix deployment needed? — if production is affected, coordinate a patch release per MIN-06 / deployment playbook - Do not push until the user approves ## Rules to Follow Before fixing, read each Rule below in this playbook (by slug), then apply it: - `do-test-first` - `do-not-mock-in-integration-tests` - `do-follow-commit-convention` - `do-small-increments` - `do-informative-logging` (when the fix touches decision points) ## Success Criteria - Root cause of the test gap identified and documented - Failing test proves the bug before the fix - Fix implemented; proving tests pass - Full regression green (100% pass rate) - Commit made; user decision recorded on integrate / PR / hotfix ## Inputs Read these before starting this activity. - Bug Report (Document, Required) — produced by Check Definition of Done (#101), Finalize Feature (#102), or Acceptance, Bug Reports & Deploy Fixes (#183) via `report_bug` MCP tool or Feedback UI.
Readiness Check	PIN-1	Plan Iteration	Junior Edda	Construction (#3)	Read the 'PIN-1 Readiness Check' activity from playbook 'Junior Edda' (workflow 'Plan Iteration'). Follow its guidance when assisting me. ## Purpose Validate all prerequisites before planning begins. User provides a goal sentence (e.g. "we aim to complete act-11"). Each gate is checked in order — if any fails, stop with specific remediation instructions. ## Input The user's stated goal sentence. Example: "we aim to complete act-11" or "implement team management features". ## Gates ### Gate 1 — BSP (Bootstrap) Check that the project has been bootstrapped: ```bash test -f Makefile && echo "PASS" \|\| echo "FAIL: Run BSP workflow — project not bootstrapped" test -f requirements.txt && echo "PASS" \|\| echo "FAIL: Run BSP workflow — requirements.txt missing" ``` If either fails: STOP — "Project not bootstrapped. Run the BSP (Bootstrap Project) workflow first." ### Gate 2 — User Journey Coverage Identify the target act from the user's goal (e.g. "act-11", "team management"). Check `docs/features/user_journey.md` for a matching section: ```bash grep -i "act-{N}" docs/features/user_journey.md && echo "PASS" \|\| echo "FAIL" ``` If missing: STOP — "No user journey section found for {target}. Add the act section to `docs/features/user_journey.md` before planning." ### Gate 3 — Feature Specs (BDD) Check that `docs/features/act-{N}/` exists and contains `.feature` files: ```bash ls docs/features/act-{N}/.feature 2>/dev/null && echo "PASS" \|\| echo "FAIL" ``` If missing: STOP* — "No feature specs found for act-{N}. Run the ESM (Envision the System) workflow to produce `.feature` files." ### Gate 4 — Architecture (SAO.md) ```bash test -f docs/architecture/SAO.md && echo "PASS" \|\| echo "FAIL" ``` If missing: STOP — "No `docs/architecture/SAO.md` found. Run the DTA (Define Architecture) workflow first." ### Gate 5 — AI IDE Config (DSP) ```bash test -f CLAUDE.md && echo "PASS" \|\| echo "FAIL" ``` If missing: STOP — "No `CLAUDE.md` found. Run the DSP (Deploy Software Process) workflow to configure the AI IDE." ### Gate 6 — Agent proof harness (optional; when SAO §17 applies) When `docs/architecture/SAO.md` §17 documents in-app LLM agents (not "Not applicable"): ```bash test -f tests/support/agent_story.py && echo "PASS" \|\| echo "FAIL: TFK-02 must bootstrap tests/support/agent_story.py before agent-feature BPE" ``` If SAO §17 is N/A: SKIP — record `agent_harness: n/a`. If SAO §17 applies and the file is missing: STOP — "Agent proof helper missing. Run TFK-02 (Bootstrap Test Harness) to create `tests/support/agent_story.py` and ScriptedLLM fixtures before planning agent features." ## Mockup Check (advisory, after all gates pass) ```bash ls docs/ux/mockups/act-{N}/ 2>/dev/null && echo "Mockups found" \|\| echo "No mockups" ``` If no mockups: ask — "No mockups found for {target}. Create them per ESM-04 before planning? (yes/no)" - Yes → run ESM-04, then return to PIN-01 after mockups are created - No → proceed with feature specs only ## Output When all gates pass: - `target_act`: extracted act identifier (e.g. "act-11") - `feature_files[]`: list of `.feature` files in `docs/features/act-{N}/` - `has_mockups`: boolean - `agent_harness`: `ready` \| `n/a` (from Gate 6) Proceed to PIN-02 Orient & Validate Scope. ## Success Criteria - All required gates pass (Gates 1–5; Gate 6 pass or skipped when SAO §17 N/A) - User has confirmed mockup status - `target_act` and `feature_files[]` identified - `agent_harness` recorded when SAO §17 applies
Orient & Validate Scope	PIN-2	Plan Iteration	Junior Edda	Construction (#3)	Read the 'PIN-2 Orient & Validate Scope' activity from playbook 'Junior Edda' (workflow 'Plan Iteration'). Follow its guidance when assisting me. ## Purpose Build the iteration orient summary from the feature files identified in PIN-01, using historical lesson data where available. Establishes what the iteration will deliver and any risk flags. ## Session Resume Check If `docs/plans/iterations/pin-orient-{today's date}.md` already exists → skip this activity, load it as the orient summary, proceed to PIN-03. ## Prerequisites - `target_act` and `feature_files[]` from PIN-01 - `docs/lessons_learned/ITER-.md` files (may not exist on first iteration) ## Steps ### Step 1: Read Feature Specs For each file in `feature_files[]`, read the BDD scenarios. Extract: - Scenario titles - Given/When/Then outlines (to understand scope boundaries) - Tags if present (e.g. `@wip`, `@smoke`) — optional; scenarios with no tags are treated as fully eligible ### Step 2: Read Learning Log ```bash ls -t docs/lessons_learned/ITER-.md 2>/dev/null \| head -5 ``` If no files found → first iteration. Create the directory and continue with first-iteration defaults: ```bash mkdir -p docs/lessons_learned ``` - `velocity_ratio`: unknown - `dominant_drift`: none - `footprint_accuracy`: unknown If files found → read the 5 most recent. Each file has YAML frontmatter. Extract: ```bash for f in $(ls -t docs/lessons_learned/ITER-.md \| head -5); do awk '/^---/{p++} p==1{print} p==2{exit}' "$f" done ``` Compute across the 5 most recent entries: - velocity_ratio trend: improving (trend up) / stable / degrading (trend down) - dominant_drift: most frequent non-none value (or "none" if all none) - footprint_accuracy trend: improving / stable / degrading Also scan the body of the most recent file for flagged SAO.md decisions. If any are present: > "Prior iteration flagged SAO.md decisions not yet applied: {list}. Verify they were committed before this iteration begins." Note:* `docs/lessons_learned/log.yaml` is deprecated. If it exists, ignore it. ### Step 3: Validate Scope - If `velocity_ratio` degrading AND >2 scenarios: flag scope risk - If `dominant_drift` was `footprint_violation` in 2+ of last 5: flag complexity risk ### Step 3b: Scope Bounding Count total scenarios across all `feature_files[]`. Assess whether the full scope fits your effective context window: - Estimate complexity: scan each scenario's step count and whether it touches new models, new pages, or new infrastructure. - If the full scope feels manageable (scenarios are simple CRUD / UI checks with predictable footprints), proceed with all scenarios. - If the scope is large and scenarios are complex (new models, cross-cutting concerns, unresolved system dependencies), ask: > "This iteration has {N} scenarios. Some appear complex — would you like to: > A) Proceed with all {N} > B) Take a subset (tell me which scenarios or feature files) > C) Split across multiple iterations — first file's scenarios now, remainder via a second PIN run" Handle user response: - A: Proceed with all scenarios; record `scope_override: confirmed` in orient summary - B: Filter to the user-selected subset; record deferred scenarios in `scenarios_deferred[]` - C: Take only the first feature file's scenarios (or user-specified first batch); record `scope_deferred_files[]` If the full scope is simple and clearly manageable, do not ask — just proceed and note `scope_override: not_needed`. ### Step 4: Write Orient Summary Create `docs/plans/iterations/pin-orient-{YYYYMMDD}.md`: ```markdown ## Orient Summary — {date} ### Target Act: {target_act} Feature files: {list} ### Scenarios in Scope {list of scenario titles — after scope bounding} ### Scenarios Deferred {list or "None"} ### Velocity Trend {improving/stable/degrading or "First iteration"} ### Dominant Drift {signal_type or "None — first iteration"} ### Scope Validation {per-scenario risk flags or "No risks detected"} ``` ## Success Criteria - Orient summary written to `docs/plans/iterations/pin-orient-{date}.md` - Scenarios in scope identified (after scope bounding — may be a subset of all feature file scenarios) - Deferred scenarios recorded if scope was reduced - Risk flags computed or noted as first iteration - Ready for PIN-03
Contract	PIN-3	Plan Iteration	Junior Edda	Construction (#3)	Read the 'PIN-3 Contract' activity from playbook 'Junior Edda' (workflow 'Plan Iteration'). Follow its guidance when assisting me. ## Purpose For each BDD scenario in scope: plan and skeleton it. Planning (BPE-01 — Activity 96, Plan Feature — reasoning: context map, do-not-do list, applicable SAO sections, checkpoint commands, drafted skeleton content) is dispatched in parallel, one worker per scenario — it is pure analysis with no repository writes, so there is nothing to conflict over yet. Applying those plans to the working tree (writing skeleton files, verifying checkpoints, committing) is done sequentially, one scenario at a time, because that is where real git state is touched. After all scenarios are applied, derive the file-level conflict map from the real commits and write the execution manifest YAML — unchanged from before. Scope note: this PIP changes how scenario planning and skeleton-writing happen (Steps 2-5, below). It does not change the activity's boundary — Steps 6-8 (conflict map, parallel groups, manifest) stayed inside this same activity in the pre-existing version of Contract, and stay here for the same reason: the manifest can't be written until every scenario's real footprint is known, which only happens at the end of Step 5. Splitting manifest-writing into a separate activity is a legitimate structural question, but it's orthogonal to fan-out and is not addressed by this PIP. ## Prerequisites - Orient summary from PIN-02 - `docs/architecture/SAO.md` - BDD feature specs from `docs/features/act-{N}/` ## Step 1: Create Iteration Branch (once) ```bash # Safe for retries — checks before creating git show-ref --verify --quiet refs/heads/iteration/YYYYMMDD-{goal-slug} \ && git checkout iteration/YYYYMMDD-{goal-slug} \ \|\| git checkout -b iteration/YYYYMMDD-{goal-slug} ``` ## Step 2: Dispatch Planning Workers (parallel — one per scenario) Apply rule `do-fan-out-independent-work`. The item list is every scenario in scope. Each worker performs pure analysis and returns a plan — it must not write to the working tree or make any commit. For each scenario, a worker does: a) Read Specification and Record Feature File Path. Read the BDD feature spec for this scenario. Note the exact `.feature` file path. Record: `feature_file_path: docs/features/act-{N}/{filename}.feature` Read `docs/architecture/SAO.md`. Note governing sections. b) Identify System Dependencies. Scan the scenario's steps for capabilities requiring external infrastructure not part of this feature's own footprint: Common patterns to check for: - "receives a notification" → `notification_service` - "receives an email" → `email_backend` - "background task" → `task_queue` - "search index" → `search_backend` If found, record as `system_dependencies` and propose a resolution — but do not act on Option A or C unilaterally; a worker cannot ask the user mid-dispatch while other workers are also running. Instead the worker records its proposed resolution for the orchestrator to batch: \| Option \| When to use \| Worker records \| \|--------\|-------------\|-----------------\| \| A — Prerequisite scenario \| Infrastructure reusable across multiple scenarios \| Proposed new scenario S0 + which scenarios would depend on it. Orchestrator batches all such proposals and asks the user once, after all workers report. \| \| B — Stub & proceed \| Infrastructure is minor, can be stubbed \| Worker proceeds autonomously: notes stub in its plan, drafts a stub file named exactly after the dependency identifier under the project's existing service-module path (e.g. `notification_service` → `methodology/services/notification_service.py` — this naming convention is pre-existing in Contract, unchanged by this PIP), annotates its manifest entry as `notification_service [STUBBED]`. No user round-trip needed. \| \| C — Skip this iteration \| Infrastructure substantial, out of scope \| Worker flags scenario as a proposed removal from `scenarios_in_scope[]`. Orchestrator batches all such proposals and asks the user once. \| c) Run BPE-01 (Activity 96, Plan Feature). Follow BPE/BPE-01 completely, in planning mode. Output must include: - Context Map — 3–5 `file:line_range` references with one-line note each - Do-Not-Do List — derived from SAO.md sections - Applicable SAO.md Sections — by heading name - Checkpoint Command — pytest command proving behavior done - Log Story Script — from BPE-01 Section E (Where / Beat / Trigger / Must include) - Log-story tests + command, when Section E is non-empty Important: skip BPE-01 Step 9 (Submit for Approval) and Step 10 (GitHub/Issue Management) — captured in the manifest instead; PIN-04 creates issues. d) Draft the skeleton — as text, not a write. Draft every class and method (public and private helpers) the implementor will need. The skeleton is the complete architecture; an implementor must not need to add new methods. ```python class FeatureService: def execute(self, id: int, user) -> dict: """ :param id: Feature ID. Example: 42 :param user: Requesting user. :return: dict. Example: {"id": 42, "name": "..."} :raises PermissionError: If user cannot access :raises ValueError: If not found """ raise NotImplementedError() def _validate(self, id, user) -> None: raise NotImplementedError() def _serialize(self, obj) -> dict: raise NotImplementedError() ``` e) Return the worker's report. Each worker's output: proposed `codebase_footprint` (file paths it expects to create/modify — an estimate, not yet a git diff), the drafted skeleton content in full, and all of (a)-(d). This is returned to the orchestrator; nothing is written to disk yet. ## Step 3: Resolve Batched Proposals Collect every Option-A and Option-C proposal from Step 2b across all workers. Present them to the user together, once: > "N workers flagged shared-infrastructure or scope proposals: {list}. Confirm before I apply skeletons." Apply the user's decisions: add any approved S0 prerequisite scenarios (looping them through Step 2 themselves before continuing), remove any approved scope exclusions from `scenarios_in_scope[]` into `scenarios_deferred[]`. ## Step 4: Sanity-Check Proposed Footprints Before writing anything, compare workers' proposed footprints pairwise. If two scenarios propose creating the same new file, resolve it now — ask the user which scenario owns it, or merge the two plans — rather than discovering the collision after skeletons are already committed. ## Step 5: Apply Skeletons Sequentially For each scenario (order no longer matters for contention — planning is already done, this pass is now fast mechanical work): 1. Write the drafted skeleton content to disk. 2. Verify checkpoint commands: ```bash {checkpoint.command} 2>&1 \| tail -5 # When log_tests present: {checkpoint.log_story_command} 2>&1 \| tail -5 ``` Acceptable: `NotImplementedError` or `collected 0 items`. Not acceptable: `ImportError`, `SyntaxError`. 3. Commit: ```bash git add -A git commit -m "chore(pin): skeleton S{N} — {scenario title}" ``` 4. Record the actual footprint (authoritative — supersedes the worker's proposed footprint from Step 2e): ```bash git diff HEAD~1 --name-only ``` Record as `codebase_footprint[]`. Record `skeleton_commit` hash. ## After All Scenarios Are Applied (same activity, same boundary as before this PIP — see Scope note above): ### Step 6: Build Conflict Map For each scenario pair, check actual footprint intersection: ``` S1 ∩ S2 = {tools.py} → CONFLICT → serialize S1 ∩ S3 = {} → no conflict → parallel ``` ### Step 7: Assign Parallel Groups Non-conflicting → same group. Conflicting → different groups with dependency. (This grouping feeds MIN-03's build-time dispatch — not this activity's own already-completed apply pass.) ### Step 8: Write Execution Manifest Create `docs/plans/iterations/ITER-YYYYMMDD-HHmm-{goal-slug}.yaml`. `doctrine_version` below is a free-text version tag inside this manifest template (not a separate Mimir entity); it is bumped from the pre-existing "2.0" to "2.1" to signal that the manifest is now produced by the fan-out process this PIP introduces, not because a new lookup entity was added: ```yaml iteration: goal: "{iteration_goal}" doctrine_version: "2.1" created_at: "{ISO8601}" conflict_map: path/to/file.py: [S1, S2] parallel_groups: A: [S1] B: [S3] C: [S2] drift_thresholds: absorbed: checkpoint_fail_retry: 1 escalated: footprint_violation: true method_explosion: true sao_violation: true checkpoint_fail_after_retry: true scenarios: S1: title: "{title}" parallel_group: A skeleton_commit: "{hash}" codebase_footprint: [...] feature_file_paths: - docs/features/act-{N}/{filename}.feature system_dependencies: - notification_service # or empty list [] if none; append [STUBBED] if stubbed log_story_script: - {beat: entry, where: "LoginView.post", trigger: method_called, must_include: ["email="]} - {beat: branch, where: "LoginView.post", trigger: bad_credentials, must_include: ["authentication failed"]} log_tests: - {name: test_login_log_story_reject, path: src/yggdrasil/auth/tests/test_login_view.py} checkpoint: command: "pytest ...::test_login_post_failure_rerenders_with_error -x" expected_exit_code: 0 log_story_command: "pytest ...::test_login_log_story_reject -x" # required when log_tests non-empty dependencies: [] context_map: [...] do_not_do: [...] sao_sections: [...] ``` Rules: - If `log_tests` is non-empty, `checkpoint.log_story_command` is required - Omit `log_story_script` / `log_tests` / `log_story_command` only when BPE-01 Section E is empty (document why) - PIN-04 consumers may embed both commands in the issue SCENARIO block ## Rules Before dispatching planning workers and writing the manifest, read each Rule below in this playbook (by slug), then apply it. Do not rely on memory of the rule text. Required: - `do-plan-before-doing` - `do-fan-out-independent-work` - `do-skeletons-first` - `do-test-first` - `do-informative-logging` - `do-assert-log-story` - `do-follow-commit-convention` - `do-small-increments` - `pytest` Activity-specific (not a substitute for the rules above): - Planning workers (Step 2) never write to the working tree or commit — only the sequential apply pass (Step 5) does. - When BPE-01 Section E (Log Story Script) is non-empty, the manifest must include `log_story_script[]`, `log_tests[]`, and `checkpoint.log_story_command`. ## Success Criteria - Every in-scope scenario planned by a dedicated worker before any skeleton is written - Batched Option-A/Option-C proposals resolved with the user in a single round-trip, not per-worker - Proposed footprints sanity-checked for same-file collisions before Step 5 - Skeleton committed for every scenario, with the actual git-diff footprint recorded (not the proposed one) - `feature_file_paths[]` recorded per scenario - `system_dependencies[]` recorded per scenario (empty list if none) - All system_dependencies resolved (stubbed, prerequisite scenario, or deferred) before the manifest is written - Stub files named to match their dependency identifier so MIN-04's codebase check succeeds - Execution manifest YAML written to `docs/plans/iterations/` - Conflict map derived from actual skeleton commits - All checkpoint commands verified (NotImplementedError or 0 items), including `log_story_command` when declared
Publish	PIN-4	Plan Iteration	Junior Edda	Construction (#3)	Read the 'PIN-4 Publish' activity from playbook 'Junior Edda' (workflow 'Plan Iteration'). Follow its guidance when assisting me. ## Purpose Create the Milestone and Issues from the execution manifest, on GitHub or GitLab. Ask user before creating. The Milestone becomes MIN's operational ground truth — it must contain the full YAML manifest inline. ## Prerequisites - Execution manifest YAML from PIN-03 (`ITER-.yaml`) with `milestone_number: null` placeholder - All skeleton commits on iteration branch - GitHub CLI (`gh`) or GitLab CLI (`glab`) authenticated ## Step 0 — Platform Detection ```bash REMOTE=$(git remote get-url origin 2>/dev/null \|\| echo "") if echo "$REMOTE" \| grep -q "github.com"; then PLATFORM=github gh auth status \|\| { echo "Run: gh auth login"; exit 1; } elif echo "$REMOTE" \| grep -q "gitlab"; then PLATFORM=gitlab glab auth status \|\| { echo "Run: glab auth login"; exit 1; } else echo "Cannot detect platform from git remote. Set PLATFORM=github or PLATFORM=gitlab manually." exit 1 fi echo "Platform: $PLATFORM" ``` ## Step 1 — User Gate Ask: "Platform detected: {github\|gitlab}. Create milestone and issues from the manifest? (yes/no)" - No* → write manifest to `docs/plans/iterations/` only. Stop. Inform user: "Manifest saved. Invoke MIN manually when ready." - Yes → continue. ## Step 2 — Bootstrap Labels GitHub: See GitHub Issue Operations skill — Bootstrap Labels section. GitLab: See GitLab Issue Operations skill — Bootstrap Labels section. ## Step 3 — Create Milestone GitHub: ```bash MILESTONE_NUMBER=$(gh api repos/{owner}/{repo}/milestones \ --method POST \ --field title="ITER-YYYYMMDD \| {iteration_goal}" \ --field description="<!-- MANIFEST --> $(cat {manifest_path}) <!-- /MANIFEST --> ## Iteration Goal {iteration_goal} ## Scenarios {list}" \ --jq '.number') echo "Milestone: #$MILESTONE_NUMBER" ``` GitLab: ```bash PROJECT=$(glab api projects/:fullpath --jq '.id') MILESTONE_NUMBER=$(glab api "projects/$PROJECT/milestones" \ --method POST \ --field title="ITER-YYYYMMDD \| {iteration_goal}" \ --field description="<!-- MANIFEST -->$(cat {manifest_path})<!-- /MANIFEST -->" \ --jq '.iid') echo "Milestone: #$MILESTONE_NUMBER" ``` ## Step 4 — Create Issues (one per scenario) For each scenario in manifest order: GitHub: See GitHub Issue Operations skill — Pattern 2. GitLab: See GitLab Issue Operations skill — Pattern 2. Issue body must include inline: - `<!-- SCENARIO -->` YAML block - `<!-- FEATURE_EXECUTION_GRAPH -->` YAML block (full graph for this scenario) - Context Map table - Do Not Do list - SAO.md Sections - Implementation Plan (full text from BPE-01) - Acceptance Criteria checklist — one checkbox per graph node plus scenario rollup checkpoint Labels: `status-queued, parallel-group-{X}` Dependency issues reference each other in body. ## Step 5 — Update Manifest with Milestone Number and Issue Numbers After the milestone is created (Step 3) and all issues are created (Step 4), update the manifest: ```bash # Write milestone_number into the iteration block python3 -c " import re content = open('{manifest_path}').read() content = re.sub(r'milestone_number: null', 'milestone_number: {milestone_number}', content, count=1) open('{manifest_path}', 'w').write(content) " # Also add github_issue or gitlab_issue per scenario (as before) # Edit the manifest YAML to add the issue number under each scenario key ``` Commit both updates together: ```bash git add docs/plans/iterations/ git commit -m "chore(pin): add milestone #{milestone_number} and issue numbers to manifest ITER-YYYYMMDD" ``` Verification: `milestone_number` in the manifest must now be an integer, not `null`. MIN-01 uses this field to locate the correct manifest. Do not proceed to PIN-05 if it is still `null`. ## Step 6 — Verify GitHub: ```bash gh milestone view {milestone_number} gh issue list --milestone {milestone_number} ``` GitLab: ```bash glab api "projects/:fullpath/milestones" --jq '.[] \| select(.title \| contains("ITER"))' glab issue list --milestone "{milestone_title}" --label "status-queued" ``` ## Success Criteria - Milestone created with full `<!-- MANIFEST -->` YAML block - One Issue per scenario with inline `<!-- SCENARIO -->` + `<!-- FEATURE_EXECUTION_GRAPH -->` + context map + do-not-do + implementation plan - All issues labelled `status-queued` + `parallel-group-{X}` - `milestone_number` written back to manifest (not null) - Local manifest updated with milestone number + issue numbers and committed ## Skills - GitHub Issue Operations (gh CLI) - GitLab Issue Operations (glab CLI)
Human Acceptance	PIN-5	Plan Iteration	Junior Edda	Construction (#3)	Read the 'PIN-5 Human Acceptance' activity from playbook 'Junior Edda' (workflow 'Plan Iteration'). Follow its guidance when assisting me. ## Purpose Verify CLAUDE.md iteration protocol sections are current, obtain explicit human approval, and deliver the single activation instruction for MIN. This is the final gate — do not proceed without explicit human go. STOP — mandatory human gate. ## Prerequisites - All skeleton commits on iteration branch - Execution manifest finalized (`ITER-.yaml`) with `milestone_number` populated - GitHub/GitLab Milestone + Issues published (PIN-04 complete) ## Steps ### Step 1: Verify CLAUDE.md Iteration Protocol Sections Read the `## Iteration Protocol`, `## Drift Handling`, `## Session Resume Protocol`, and `## Authority Model` sections of CLAUDE.md. Required sections must exist and contain: - Iteration Protocol* — references `<!-- MANIFEST -->` block, `status-queued`, fresh subagent per `feature_execution_graph` node with pytest gates - Drift Handling — absorbed and escalated thresholds (checkpoint_fail retry once; escalate on footprint_violation, method_explosion, sao_violation) - Session Resume Protocol — find `status-in-progress` → re-run checkpoint → PASS: close and continue / FAIL: retry - Authority Model — can-decide / must-escalate / cannot-do bounds for the iteration runner If any section is missing or substantially absent: update CLAUDE.md and commit: ```bash git commit -m "docs(claude): sync iteration protocol to current MIN workflow" ``` Do NOT compare against a `doctrine_version` field in the manifest — protocol version is managed by the Edda playbook release, not the manifest. ### Step 2: Present Review Summary ``` === PIN COMPLETE — REVIEW REQUIRED === Iteration: {iteration_goal} Milestone: #{milestone_number} — {milestone_title} Scenarios: {N} \| Groups: {A,B,...} {for each scenario:} S{N} [{group}] {title} Checkpoint: {command} Graph nodes: {N} (BPE-02...06) Footprint: {N} files Depends on: {deps or "none"} Sample: review one scenario's feature_execution_graph in Plan mode Conflict map: {file} -> [{S_N}, {S_M}] (serialized) {or "No conflicts — all scenarios parallel"} Platform: {github\|gitlab} Milestone: #{milestone_number} CLAUDE.md protocol: {current / updated at {timestamp}} Activate MIN with: "Work on Milestone #{milestone_number}" ====================================== ``` ### Step 3: Await Human Decision GO — "Approved" or "Work on Milestone #{N}" ```bash # GitHub: gh issue comment {first_issue} --body "PIN approved at {timestamp}. MIN authorized." # GitLab: glab issue note {first_issue} --message "PIN approved at {timestamp}. MIN authorized." ``` NO-GO options: - Skeleton issue on S{N} → return to PIN-03 for that scenario only - Re-sequencing needed → return to PIN-03 Step 8-9 to revise conflict map - Drop S{N} → close issue (won't-fix), remove from manifest, update Milestone description ## Success Criteria - CLAUDE.md iteration protocol sections are current (no doctrine_version comparison) - Explicit human go/no-go decision obtained - If go: approval comment posted on GitHub/GitLab - Human has the activation instruction with the concrete milestone number ## Rules - Never skip this gate regardless of time pressure - If human is unavailable: pause PIN, do not proceed to MIN - A no-go with a fix takes minutes; a bad MIN run wastes an hour
Activate Iteration	MIN-1	Manage Iteration	Junior Edda	—	Read the 'MIN-1 Activate Iteration' activity from playbook 'Junior Edda' (workflow 'Manage Iteration'). Follow its guidance when assisting me. ## Purpose Activate the iteration from a single human trigger. Confirm the correct PIN manifest exists for the requested milestone, validate PIN readiness (no contradictory or non-executable scenarios), assert every issue is open and queued, and declare a clean execution slate. Trigger: user says "Work on Milestone #N" or "Work on Milestone <name>" ## Step 0 — Locate Milestone-Bound Manifest (do this FIRST) Find the manifest using the `milestone_number` or `milestone_title` fields written by the Publish activity in Plan Iteration. Do NOT use "newest file" or `ls -t \| head -1`. ```bash # When user provides a milestone number (#N): grep -l "milestone_number: {N}" docs/plans/iterations/ITER-.yaml 2>/dev/null # When user provides a milestone name or fragment: grep -rl "milestone_title:.{title_fragment}" docs/plans/iterations/ITER-.yaml 2>/dev/null ``` If no matching manifest: > STOP.* No manifest bound to this milestone. Tell user: "Run Plan Iteration for milestone '{name}' first, then invoke Manage Iteration." If `milestone_number: null` (or field absent) in the matched file: the Publish activity did not complete its manifest update. Tell user: "Plan Iteration Publish step did not write the milestone number back to the manifest. Re-run Publish Step 5, then invoke Manage Iteration." If multiple matches: confirm with user which manifest to use. Record the selected manifest path. All subsequent steps use this file only. ## Step 1 — Find and Lock the Milestone ```bash gh milestone list --json number,title,state \| jq '.[] \| select(.state == "open")' ``` Match to exactly one open milestone. Store `{milestone_number}` and `{milestone_title}`. Multiple matches or no match → stop and ask user to clarify. Cross-check: confirm the manifest's `milestone_number` matches `{milestone_number}` AND `milestone_title` matches `{milestone_title}`. Any mismatch → stop and report. ## Step 2 — PIN Readiness Validation Before touching any issue, validate that the manifest scenarios are executable: ```bash cat {selected_manifest} \| grep -A1 'feature_file_paths' \| grep '\.feature' ``` For each `feature_file_paths[]` entry, verify: - [ ] The `.feature` file exists on disk - [ ] Each `Scenario:` title is unique within that file - [ ] URLs referenced in steps are consistent (flag alternating paths as a spec conflict) - [ ] No scenario step is irreducibly vague — flag and ask user before proceeding If any conflict or ambiguity is found: > STOP. List each conflict with file + line reference. Tell user: "Plan Iteration produced contradictory or non-executable scenarios. Reconcile these before Manage Iteration can run." Do not proceed past this step with unresolved spec conflicts. ## Step 3 — Confirm Issues + Sprint-Size Guard Fetch each issue one at a time: ```bash gh issue view {github_issue} --json number,title,labels,state ``` Confirm each is `open` with `status-queued`. Report discrepancies. Sprint-size guard: ```bash gh api repos/{owner}/{repo}/milestones/{N} --jq '.open_issues' ``` If `open_issues > 15`: warn and require explicit user confirmation before continuing. ## Step 4 — Assert Clean Slate ```bash gh issue list --milestone {N} --label "status-in-progress" --json number,title ``` If any `status-in-progress` exists: prior session interrupted. Re-run its last `gate.command`. PASS → close issue, continue. FAIL → one retry → escalate. ## Step 5 — Verify Iteration Branch ```bash git branch -a \| grep "iteration/{milestone-slug}" ``` If absent: > STOP. Tell user: "Plan Iteration Contract step did not create an iteration branch. Re-run Contract Step 1 or create the branch manually before invoking Manage Iteration." Check out the iteration branch: ```bash git checkout iteration/{milestone-slug} ``` ## Step 6 — Output Activation Summary ``` === ACTIVATION === Manifest: {selected_manifest} (milestone_number: {N}, milestone_title: {title}) Milestone: #{N} \| {goal} Branch: iteration/{slug} Issues: {N} open, all status-queued Size: {ok \| WARNING: {N} issues — user confirmed} Spec: {N} feature files checked, {conflicts} conflicts, {vague} vague steps Slate: clean Next: Load Context from PIN Artifacts ================== ``` ## Success Criteria - Manifest located by `milestone_number` or `milestone_title` field (not by file order) - `milestone_number` is a concrete integer in the matched manifest (not null or absent) - Manifest `milestone_number` + `milestone_title` cross-checked against the live milestone - PIN readiness validation passed (no unresolved spec conflicts or vague steps) - Iteration branch confirmed and checked out - All issues confirmed open with `status-queued` (fetched individually) - Sprint-size warning shown if > 15 issues; user confirmed - No dangling `status-in-progress`, or resume path taken
Load Context from PIN Artifacts	MIN-2	Manage Iteration	Junior Edda	—	Read the 'MIN-2 Load Context from PIN Artifacts' activity from playbook 'Junior Edda' (workflow 'Manage Iteration'). Follow its guidance when assisting me. ## Purpose Restore the distilled context that Plan Iteration already built, then derive and present the full execution queue. Pure pre-flight — no implementation, no GitHub mutations. This activity absorbs the sequencing responsibilities of the dropped 'Sequence from Manifest' activity: loading context and building the execution queue share the same actor (TL), the same input (the iteration manifest), and the same exit condition (execution queue ready to dispatch). Do NOT re-read SAO.md, BDD specs, or mockups from scratch. ## Part A — Load Context ### Step 1: Load the Milestone-Bound Manifest Use the manifest path identified and locked in Activate Iteration. Do not re-select. Do not use `ls -t \| head -1`. ```bash cat {manifest_path_from_activate_iteration} # already on disk; read it directly ``` Extract per scenario: `id`, `title`, `github_issue`, `parallel_group`, `codebase_footprint[]`, `context_map[]`, `do_not_do[]`, `checkpoint.command`, `checkpoint.log_story_command`, `feature_execution_graph` (nodes: `id`, `bpe`, `depends_on`, `footprint[]`, `gate`), `dependencies[]`, `feature_file_paths[]`, `system_dependencies[]`. Verify that each scenario's `github_issue` is on the current milestone (cross-check with Activate Iteration's confirmed issue list). Any issue not in the milestone list → flag before proceeding. ### Step 2: Load Orient Summary ```bash ls -t docs/plans/iterations/pin-orient-.md 2>/dev/null \| head -1 ``` If none: first-iteration defaults (`velocity_trend: unknown`, `scope_risks: none`). Continue. If found: read it. Extract velocity trend, scope risks, watch-fors. ### Step 3: Spot-Check Context Map For 1-3 `context_map` entries per scenario: ```bash wc -l {file} # confirm file exists and has sufficient lines ``` Missing file → flag as potential sao_violation. ### Step 4: Check System Dependencies For each `system_dependencies[]` item, verify it exists in the codebase. If absent: STOP* and escalate before any implementation. ## Part B — Sequence ### Step 5: Parse Parallel Groups + Conflict Map From the manifest: extract `parallel_groups` and `conflict_map`. Do not recompute — Plan Iteration Contract derived these from actual skeleton commits. ### Step 6: Check Dependency State Per Scenario For each scenario, fetch each `dependencies[]` issue individually: ```bash gh issue view {N} --json number,state,labels ``` Mark each READY (no deps, or all deps closed with status-done) or BLOCKED. ### Step 7: Build Execution Queue Order: Group A → Group B → Group C. Within each group: READY before BLOCKED. ### Step 8: Output Execution Plan (Plan Mode) Switch to Plan Mode. Present: Outer — scenario dependency graph (Mermaid flowchart) Inner — for each READY scenario, feature_execution_graph node dependencies ``` === CONTEXT LOADED === Manifest: {path} — bound to milestone #{milestone_number} Orient: {filename or "first iteration"} \| velocity_trend: {value} Scenarios: {N} total System deps: {list or "none"} Spot-check: {N}/{N} context_map refs confirmed === EXECUTION QUEUE === Groups: {N} \| Ready: {N} \| Blocked: {N} {queue with nodes per scenario} First ready nodes: {list} Conflicts: {file shared by SN, SM — serialized} Next: Execute (TL Dispatches Workers) ======================= ``` ## Success Criteria - Manifest loaded from the path locked in Activate Iteration (not re-selected) - Every scenario's `github_issue` confirmed on the milestone - All per-scenario fields extracted - System dependencies verified; escalation if absent - Parallel groups + conflict map parsed (not recomputed) - Execution queue ordered; Mermaid diagrams presented
TL Dispatches Workers to Build	MIN-3	Manage Iteration	Junior Edda	—	Read the 'MIN-3 TL Dispatches Workers to Build' activity from playbook 'Junior Edda' (workflow 'Manage Iteration'). Follow its guidance when assisting me. ## Model Tiers \| Role \| Model tier \| Responsibility \| \|------\|-----------\|----------------\| \| Team Lead (TL) \| Advanced reasoning model \| Sequences queue, dispatches workers, reviews NODE_PASS, handles drift — writes no feature implementation code \| \| dr-dobbs (Worker) \| Cheap-fast model \| Implements one graph node per invocation, commits its changes, runs gate, posts NODE_PASS or NODE_FAIL, stops \| TL authority on code: TL may fix trivial presentation issues inline (e.g. add a missing `data-testid` attribute to an HTML element, correct an import order). TL may NOT write new logic, new methods, new tests, or multi-line implementation — that is dr-dobbs work. When in doubt: dispatch a worker. Worker isolation: Each worker operates on the shared iteration branch. Workers with overlapping `footprint[]` files are serialized by the `conflict_map` (already computed by PIN). Do not dispatch workers that share files in the same parallel slot. Workers must commit their own footprint before posting NODE_PASS to prevent dirty-tree races. --- ## Step 1: Verify Iteration Branch Is Checked Out ```bash git branch --show-current # must match iteration/{milestone-slug} git status # must be clean before any dispatch ``` If dirty: do not dispatch. Identify and commit or stash uncommitted changes from a prior session. ## Step 2: Pick the Next READY Issue From the execution queue (MIN-02), select the next READY scenario respecting group order A → B → C and `conflict_map` constraints. Claim: ```bash gh issue edit {N} --add-label "status-in-progress" --remove-label "status-queued" gh issue comment {N} --body "<!-- EXECUTION_START -->\nStarted: {ISO8601}\nBranch: iteration/{slug}\n<!-- /EXECUTION_START -->" ``` ## Step 3: Read the Feature Execution Graph ```bash gh issue view {N} --json number,title,body,labels ``` Parse `<!-- FEATURE_EXECUTION_GRAPH -->` from issue body. Extract all nodes and identify the first ready nodes (no `depends_on`, or all deps already NODE_PASS). ## Step 4: Dispatch Worker Subagents (one per ready node) For each ready node, assemble the dr-dobbs task prompt. Commit type mapping (use as `{bpe_type}` in the commit message below): \| Node `bpe` value \| Commit type \| \|-----------------\|-------------\| \| BPE-02, BPE-03 \| `feat` \| \| BPE-04, BPE-05 \| `test` \| \| BPE-06 \| `chore` \| The prompt must include an explicit commit step: ``` You are dr-dobbs — cheap-fast implementation worker on iteration branch: iteration/{slug}. Implement ONLY node {node_id} for issue #{N}. 1. Confirm you are on the correct branch: git branch --show-current # must be iteration/{slug} 2. Read the issue: gh issue view {N} --json number,title,body,labels 3. Assemble guidance bundle per skill "Assemble Guidance Bundle" for this node. 4. Implement only footprint[]: {footprint_list} - Fill raise NotImplementedError() stubs. Do NOT change method signatures. - If new models: run makemigrations && migrate before gate. 5. Run gate: {gate.command} {gate.log_story_command if declared} 6. If gate PASS: a. git add {footprint_files} b. git commit -m "{bpe_type}({scope}): {node_id} — {issue_title} (#{N})" (bpe_type: feat for BPE-02/03, test for BPE-04/05, chore for BPE-06) c. Post NODE_PASS: <!-- NODE_PASS --> node: {node_id} gate: {command} — exit 0 commit: {sha} <!-- /NODE_PASS --> d. Stop. Do not continue to the next node. 7. If gate FAIL: one targeted fix, retry gate once. PASS → commit and NODE_PASS as above. FAIL → post NODE_FAIL (with error excerpt) and stop. Do NOT: change signatures, touch files outside footprint[], create files not in skeleton, pick up another node. ``` Launch as a fresh Task subagent (cheap-fast model). Never resume a prior worker. ## Step 5: Monitor and Advance the Node Graph On NODE_PASS: confirm the commit SHA is present in the comment. Check which nodes are newly unblocked; dispatch workers. Continue until all nodes show NODE_PASS. On NODE_FAIL (after worker's internal retry): post absorbed drift comment; dispatch one TL-guided targeted fix subagent. If that also fails: escalate with `drift-escalated` label. On footprint violation: escalate immediately. ## Step 6: Handoff to MIN-04 ```bash gh issue comment {N} --body "<!-- BUILD_COMPLETE -->\nAll nodes NODE_PASS.\nBranch: iteration/{slug}\nReady for: MIN-04\n<!-- /BUILD_COMPLETE -->" ``` Begin MIN-04 for this issue. Parallel scenarios: MIN-04 may process one while MIN-03 dispatches nodes for another, provided they don't share files. ## Drift Table \| Signal \| Threshold \| Action \| \|--------\|-----------\|--------\| \| gate fail \| first \| worker retries once internally \| \| gate fail after retry \| second \| TL dispatches targeted fix worker \| \| gate fail after TL fix \| third \| ESCALATE \| \| footprint violation \| any \| ESCALATE immediately \| \| time overrun \| > 2x per node \| ESCALATE \| \| same node, 2+ absorbed \| — \| ESCALATE \| ## Success Criteria - Iteration branch confirmed clean before any dispatch - TL wrote no feature implementation code - Every worker committed its footprint files before posting NODE_PASS - Each NODE_PASS comment contains a commit SHA - Parallel nodes dispatched only where conflict_map allows (no file overlap) - All issues have BUILD_COMPLETE comment ## Agent dr-dobbs (Worker) — cheap-fast model. One node per invocation. Fills NotImplementedError stubs in declared footprint[]. Commits footprint. Runs gate. Posts NODE_PASS with SHA. Stops. Team Lead (Orchestrator) — advanced reasoning model. Reads queue, dispatches, reviews NODE_PASS commits, handles drift. No feature code. ## Skill - Assemble Guidance Bundle - Pytest Log Story Assertions (when log_story_command declared) ## Rules `do-skeletons-first`, `do-test-first`, `do-not-mock-in-integration-tests`, `do-informative-logging`, `do-assert-log-story`, `do-write-concise-methods`, `do-follow-commit-convention`, `do-small-increments`, `pytest`
TL Integrates and Gates Each Feature	MIN-4	Manage Iteration	Junior Edda	—	Read the 'MIN-4 TL Integrates and Gates Each Feature' activity from playbook 'Junior Edda' (workflow 'Manage Iteration'). Follow its guidance when assisting me. ## Purpose For each issue that posts BUILD_COMPLETE: verify the DoD node already ran (do not re-run it), run BPE-07 Finalize Feature (Activity 102 in the Build Feature workflow), and close the issue. When all issues are closed, open the iteration PR for human review. TL may fix trivial presentation issues inline only — no logic, no new tests. Runs interleaved with Execute: as soon as an issue posts BUILD_COMPLETE, start its gate cycle. --- ## TL Code Authority TL may fix inline (without dispatching a worker): - Adding a missing `data-testid` attribute to an existing static HTML element - Correcting an import order violation - Fixing a commit message format TL must dispatch a dr-dobbs worker for: - Any fix that touches logic, queries, or view code - Any missing or broken test - Any method that needs to be created or modified This authority is consistent with Execute (Activity 181). dr-dobbs workers dispatched from this activity operate under the same isolation rules as in Activity 181. --- ## Per-Issue Cycle ### Step 1: Verify All Nodes Committed and NODE_PASS ```bash # Count NODE_PASS comments — must equal total node count in the graph gh issue view {N} --json comments \| jq '[.comments[] \| select(.body \| contains("NODE_PASS"))] \| length' # Verify each NODE_PASS contains a commit SHA gh issue view {N} --json comments \| jq '[.comments[] \| select(.body \| contains("NODE_PASS")) \| select(.body \| contains("commit:"))] \| length' ``` Both counts must equal `total_nodes`. If any NODE_PASS is missing a commit SHA: return to Execute (Activity 181) to dispatch a cleanup worker. ### Step 2: Verify the BPE-06 DoD Node Ran BPE-06 (Check Definition of Done, Activity 101 in Build Feature workflow) was dispatched as a terminal node by Execute (Activity 181). Do not re-run the full checklist. Instead, verify it passed: ```bash gh issue view {N} --json comments \| jq '[.comments[] \| select(.body \| contains("NODE_PASS")) \| select(.body \| contains("BPE-06"))] \| length' ``` If the BPE-06 node did not post NODE_PASS: return to Execute (Activity 181) to dispatch it. If BPE-06 NODE_PASS is present, run a lightweight regression: ```bash pytest tests/ -x --ignore=tests/e2e -q 2>&1 \| tail -5 ``` Green → proceed. Red → dispatch targeted dr-dobbs fix worker, rerun. ### Step 3: Run BPE-07 — Finalize Feature Apply BPE-07 (Finalize Feature, Activity 102 in Build Feature workflow): 3a. Full test suite: ```bash pytest tests/ -x --ignore=tests/e2e ``` 100% pass rate required. Any failure: dispatch targeted dr-dobbs fix worker, rerun. 3b. Dependencies: no new packages missing from `requirements.txt`. 3c. Scenario terminal checkpoint: ```bash {checkpoint.command} # from manifest ``` Must exit 0. One fix attempt → retry → escalate. 3d. Finalize commit (if anything changed during gate): ```bash git add -A git commit -m "chore({scope}): BPE-07 finalize for #{N} — {feature_title}" ``` ### Step 4: Close Issue ```bash gh issue close {N} --comment "<!-- GATE_PASS -->\nBPE-06 node: NODE_PASS (worker-run)\nBPE-07: PASS\nCheckpoint: PASS\nBranch: iteration/{slug}\nReady for: Acceptance\n<!-- /GATE_PASS -->" gh issue edit {N} --remove-label "status-in-progress" --add-label "status-done" ``` ### Step 5: Advance the Queue Check Execute (Activity 181) for newly unblocked BLOCKED scenarios. --- ## Exit Gate — All Issues Integrated When all issues on the milestone are closed: ```bash gh issue list --milestone {N} --state open --json number \| jq 'length' # must return 0 ``` Then open the iteration PR: ```bash gh pr create \ --base main \ --head iteration/{slug} \ --title "Iteration {slug}: {goal}" \ --body "## Delivered\n{scenario list with issue links}\n\n## Gate\nAll issues: NODE_PASS + BPE-06 node + BPE-07 PASS\n\n## Next\nAcceptance testing runs on this branch before merge." ``` Record the PR number. Proceed to Acceptance (Activity 183 — Saga UAT on the iteration branch, do not merge yet). ## Success Criteria - Every NODE_PASS comment contains a commit SHA - BPE-06 node verified (worker-run via Execute, not re-executed by TL) - Regression suite green before each issue closes - BPE-07 Finalize applied per issue - All issues status-done with GATE_PASS - Iteration PR opened against main ## Agent None — TL inline. May dispatch targeted dr-dobbs workers for regression failures or missing BPE-06 node. ## Rules `do-test-first`, `do-not-mock-in-integration-tests`, `do-informative-logging`, `do-assert-log-story`, `do-follow-commit-convention`
Acceptance, Bug Reports & Deploy Fixes	MIN-5	Manage Iteration	Junior Edda	—	Read the 'MIN-5 Acceptance, Bug Reports & Deploy Fixes' activity from playbook 'Junior Edda' (workflow 'Manage Iteration'). Follow its guidance when assisting me. ## Purpose Saga (UAT Agent) executes acceptance tests scoped strictly to the scenarios delivered in this iteration, classifies every defect, files bug reports for blockers, and produces a UAT Report with a routing verdict. Replaces the semi-manual acceptance walkthrough with a fully-agentified, project-agnostic UAT step. ## Model Tier Saga (UAT Agent): medium reasoning model. Executes tests literally within declared scope. Classifies every failure. Never skips an assertion. Never expands scope beyond the iteration manifest. --- ## Precedence Rule (read before anything else) When test evidence conflicts with specifications: 1. Accepted feature spec (`docs/features/` files listed in `feature_file_paths[]`) — authoritative 2. Manifest contract (ITER-.yaml scenario definition) — implementation contract 3. tests/uat or tests/e2e scripts* — current behavior; may be stale relative to specs If a test assertion conflicts with the feature spec: the spec wins. File a `test-debt` issue for the stale test. Do NOT file it as a bug against the implementation. --- ## Step 1: Determine Scope Saga tests only what the iteration delivered. Scope is fixed by the manifest: ```bash cat {manifest_path} \| grep -A50 'feature_file_paths' ``` This list is Saga's test scope. Saga does NOT discover or run tests/uat/ or tests/e2e/ wholesale. ## Step 2: Survey the Test Landscape (within scope) For each feature in scope: \| Found \| Mode \| \|-------\|------\| \| `test_.py` or `.feature` + step defs in `tests/e2e/` \| Automated — run test runner \| \| Journey scripts in `tests/uat/` matching this feature \| Scripted — execute only those scenarios \| \| Only `docs/features/` with no test files \| Exploratory — derive from feature spec \| Scripted mode: when `tests/uat/` covers multiple features, execute ONLY scenarios whose `feature_file_paths[]` entry matches this iteration. Skip all others. Exploratory mode: file a `test-debt` issue recommending test file creation. ## Step 3: Pre-conditions - Server running on the iteration branch (not main) - Health check passes before any browser action - Required seed data present - For MCP tool calls: MCP server running and accessible ## Step 4: Execute Tests (per mode, per feature in scope) Automated: ```bash pytest tests/e2e/ -k "{feature_keywords}" -v ``` Scripted: Follow the journey script(s) for this feature's scenarios only: 1. Execute each DO step via browser automation or MCP tool call 2. Assert each SEE condition 3. On RECORD: capture and store placeholder value 4. On CURSOR_PROMPT: stop, display step to user, await confirmation, continue 5. On assertion failure: classify and file (Step 5) Exploratory: For each scenario in the feature spec: 1. Walk the happy path via browser automation 2. Walk the reject path (wrong credentials, empty inputs, boundary values) 3. File any unexpected behavior as a defect ## Step 5: Defect Classification and Reporting \| Severity \| Definition \| \|----------\|------------\| \| Blocker \| Core feature path broken; journey cannot continue \| \| Major \| Feature works but wrong message/redirect/UX; journey continues \| \| Minor \| Cosmetic, label mismatch; journey continues \| \| Test-debt \| Test assertion is stale (conflicts with accepted feature spec) \| ```python report_bug( description=( f"{feature_id} / {scenario_title} — {step_description}\n\n" f"Spec says: {feature_spec_assertion}\n" f"Observed: {actual}\n" f"Severity: {severity}\n" f"Evidence: {screenshot_or_log}" ), page_context=f"Acceptance — milestone #{N} — branch iteration/{slug} — {ISO8601}" ) ``` ```bash gh issue edit {bug_number} --milestone {N} --add-label "bug,{severity}" ``` Test-debt issues: label `test-debt`, no `bug` label, do not count toward blocker total. ## Step 6: UAT Report ``` === UAT REPORT === Milestone: #{N} \| {goal} Branch: iteration/{slug} Scope: {N} features from feature_file_paths[] Mode(s): {automated \| scripted \| exploratory} per feature Results by feature: {feature_id}: {N} scenarios — {passed}/{total} ... Defects: Blockers ({N}): #{list} Majors ({N}): #{list} Minors ({N}): #{list} Test-debt({N}): #{list} Verdict: {CLEAN — proceed to Close \| BLOCKERS FOUND — proceed to Fix & Reintegrate} ================== ``` If 0 blockers: skip Fix & Reintegrate, proceed directly to Close. If 1+ blockers: proceed to Fix & Reintegrate. ## Success Criteria - Scope locked to `feature_file_paths[]` from manifest (no repository-wide test discovery) - Scripted tests run only scenarios matching iteration scope - Precedence rule applied; stale test assertions filed as test-debt, not bugs - Every defect filed with severity; test-debt separated from bugs - UAT report produced with per-feature breakdown and routing verdict ## Agent Saga — medium reasoning model. Executes within declared scope. Applies precedence rule. Files defects. Produces UAT report. Cannot skip assertions, expand scope, or modify test/spec files. ## Rules `do-informative-logging`, `do-follow-commit-convention`
TL Fixes Blockers and Regresses	MIN-6	Manage Iteration	Junior Edda	—	Read the 'MIN-6 TL Fixes Blockers and Regresses' activity from playbook 'Junior Edda' (workflow 'Manage Iteration'). Follow its guidance when assisting me. ## Purpose Team Lead triages the UAT blocker list, invokes BPE-09 (Fix Bug) once per blocker, then sends Saga back for a targeted regression run over the affected scenarios. Loop until the regression verdict is CLEAN. Non-blockers are filed as deferred issues and do not gate close. Entry condition: MIN-05 Saga produced a UAT Report with `Blockers > 0`. If blockers = 0, skip this activity — proceed directly to MIN-07. --- ## Step 1: Triage Blockers Read the UAT Report. For each blocker issue: ```bash gh issue view {bug_number} --json number,title,body,labels ``` Extract: failing scenario, step ID, expected vs actual, affected feature. Group by affected file/feature. Prioritize: fix bugs that unblock the most downstream journey steps first. ## Step 2: Invoke BPE-09 Per Blocker For each blocker, run BPE-09 Fix Bug (Activity 203) as a fresh dr-dobbs subagent (cheap-fast model). The BPE-09 input is the Bug Report filed by Saga in MIN-05. Pass it directly: ``` dr-dobbs — run BPE-09 Fix Bug for bug #{bug_number}. Bug Report: gh issue view {bug_number} --json number,title,body Follow BPE-09 steps exactly: 1. Analyze why existing tests missed the bug. 2. Write a failing test that reproduces it (Red). 3. Implement the minimal correct fix (Green). 4. Full regression: pytest tests/ 5. Commit: fix({scope}): {bug_title} — Fixes #{bug_number} 6. Post NODE_PASS on the bug issue. Scope: do not touch files unrelated to this bug. Do not patch symptoms. ``` Launch as a fresh Task subagent. Never resume a prior worker. On NODE_PASS: ```bash gh issue comment {bug_number} --body "<!-- FIX_COMMITTED -->\nCommit: {sha}\nTest gap: {one-line analysis}\n<!-- /FIX_COMMITTED -->" ``` On NODE_FAIL after worker’s internal BPE-09 retry: dispatch one additional TL-guided fix subagent with a narrower prompt targeting only the failing assertion. If still failing: escalate with `drift-escalated` label and await human decision. ## Step 3: Defer Non-Blockers For each Major and Minor defect from the UAT Report: ```bash gh issue edit {issue_number} --add-label "deferred" gh issue comment {issue_number} --body "Deferred. Non-blocker from iteration {slug}. Fix in next iteration." ``` ## Step 4: Regression UAT (Saga in Regression Mode) After all blocker fixes are committed, invoke Saga as a fresh Task subagent (medium model): ``` Saga — regression run for iteration {slug}. Re-execute only the scenarios / journeys that had failures in the prior UAT report: {affected_scenario_list} Follow the full MIN-05 protocol (survey → execute → classify → report). Produce a verdict: CLEAN or NEW_BLOCKERS_FOUND. ``` CLEAN → proceed to MIN-07 TL Closes Sprint with Lessons and Release. NEW_BLOCKERS_FOUND → loop back to Step 1. Each loop iteration must make net progress (at least one fewer blocker than the prior loop). If the same blocker persists across two fix cycles: escalate. ## Exit Condition Saga regression verdict is CLEAN and no open `blocker`-labelled issues remain on the milestone. ## Success Criteria - Every UAT blocker passed through BPE-09 Fix Bug (test-gap analysis + failing test + fix + regression) - Every fix has a commit where the reproducing test was red before and green after - Full regression suite green after all fixes - Saga regression run returns CLEAN over affected scenarios - Non-blockers labeled `deferred` and removed from milestone gate - Zero open blockers before proceeding to MIN-07 ## Agent Team Lead (Orchestrator) — advanced reasoning model. Triages blockers, assembles BPE-09 prompts, monitors worker results, coordinates regression Saga invocation. dr-dobbs (Worker) — cheap-fast model. Runs BPE-09 Fix Bug per blocker: one bug per invocation, test-first, full regression before NODE_PASS. Saga (Regression UAT) — medium model. Re-runs only affected scenarios from tests/e2e or tests/uat. ## Rules - `do-test-first` (via BPE-09) - `do-not-mock-in-integration-tests` (via BPE-09) - `do-follow-commit-convention` - `do-small-increments`
TL Closes Sprint with Lessons and Release	MIN-7	Manage Iteration	Junior Edda	—	Read the 'MIN-7 TL Closes Sprint with Lessons and Release' activity from playbook 'Junior Edda' (workflow 'Manage Iteration'). Follow its guidance when assisting me. ## Purpose Final iteration close: verify the full graph execution record, run the TAF health gate, aggregate lessons learned, apply SAO updates, merge the iteration PR (human gate), tag, create GitHub Release (human gate), and close the milestone. Relationship to Activity 182 (Close Iteration): This activity supersedes Activity 182 'Close Iteration' in Workflow 17, which is deprecated by a companion DROP change in this same PIP submission. Activity 182 predates the TL/worker/Saga model tier separation and lacks the TAF gate, UAT sign-off, and human approval gates introduced here. Predecessor activities in this PIP submission: This activity follows TL Fixes Blockers and Regresses (companion ADD in this PIP, inserted after Activity 183) and TL Integrates and Gates Each Feature (companion ADD in this PIP, inserted after Activity 181 Execute). Entry conditions: - Zero open blocker issues on milestone - Acceptance testing regression verdict: CLEAN (from Activity 183) - Iteration PR open against main --- ## Agent Team Lead — advanced-reasoning AI model (companion ADD Agent in this PIP submission). Operates autonomously throughout this activity except at the two explicit STOP gates (Steps 6 and 7). At those gates the TL presents its work product and waits for human confirmation before taking irreversible actions. When a TAF CRITICAL finding requires a code fix, the TL dispatches a dr-dobbs worker (Agent [9]) and re-runs Validate Test Health (Activity 194) before proceeding. --- ## Step 1: Graph Execution Verification For every closed scenario issue: ```bash gh issue view {N} --json comments \| jq '{ node_pass: [.comments[] \| select(.body \| contains("NODE_PASS"))] \| length, bpe06_node: [.comments[] \| select(.body \| contains("NODE_PASS")) \| select(.body \| contains("BPE-06"))] \| length, build_complete: [.comments[] \| select(.body \| contains("BUILD_COMPLETE"))] \| length, gate_pass: [.comments[] \| select(.body \| contains("GATE_PASS"))] \| length }' ``` All four counts must be >= 1. Any gap: return to Execute (Activity 181) before proceeding. ## Step 2: TAF Health Gate ### 2a. Invoke Validate Test Health (Activity 194) ```bash pytest tests/ --cov=. --cov-report=term-missing make test-at 2>/dev/null \|\| echo "no test-at target" ``` Flag: tests > 10 lines without extraction, mocking violations in integration tests, coverage regression. Produce CRITICAL / WARNING / INFO summary. ### 2b. Invoke Prepare Test Report (Activity 195) - CRITICAL: dispatch dr-dobbs worker (Agent [9]), rerun Activity 194. Blocks merge. - WARNING: file `test-debt` issue, defer - INFO: document in lessons ## Step 3: Lessons Learned Aggregation Create the Iteration Lessons Learned Document (companion ADD Artifact in this PIP submission; see Skill 28 — Lessons Learned Writing): `docs/lessons_learned/ITER-{YYYYMMDD}-{slug}.md` ```markdown --- iteration: ITER-{YYYYMMDD}-{slug} milestone: #{N} — {goal} scenarios_planned: {N} scenarios_delivered: {N} fix_cycles: {N} uat_blockers_found: {N} uat_blockers_resolved: {N} test_debt_found: {N} --- ## Execution Review (per-scenario deviations and drift signals) ## Acceptance Testing (Saga scope, blockers found, fix cycles) ## Test Debt (stale tests filed, coverage gaps) ## Architecture Notes (SAO.md updates applied or deferred) ``` Consumed by: Orient & Validate Scope (Activity 140 in Plan Iteration workflow) as velocity context for the next iteration. ## Step 4: Apply SAO.md Updates Clear and non-controversial → apply to `docs/architecture/SAO.md` now. Requires human judgment → open `sao-update` issue. ## Step 5: Commit Lessons and SAO ```bash git add docs/lessons_learned/ docs/architecture/SAO.md git commit -m "docs(lessons): ITER-{YYYYMMDD}-{slug} — {N}/{N} scenarios, {N} fix cycles" ``` ## Step 6: Human Merge Gate — STOP TL presents work product. Human must say "merge" before proceeding. ``` === MERGE GATE === PR: #{pr_number} — iteration/{slug} → main Delivered: {N} scenarios Acceptance: CLEAN ({N} blockers resolved, {N} deferred) TAF: {CLEAN \| {N} warnings deferred as test-debt} Lessons: docs/lessons_learned/ITER-{YYYYMMDD}-{slug}.md Await: user says "merge" to proceed. ================== ``` On user "merge": ```bash gh pr merge {pr_number} --squash --delete-branch \ --subject "feat(iteration): {slug} — {goal}" ``` ## Step 7: Tag and Release — STOP Assemble the Release Notes Draft (companion ADD Artifact in this PIP submission) and present for human approval: ``` === RELEASE GATE === Tag target: {merge_sha} on main Release tag: ITER-{YYYYMMDD}-{slug} Draft notes: Delivered: {scenario list with issue links} Acceptance: CLEAN Test health: {summary} Deferred: {list or none} Await: user says "release" to proceed. ==================== ``` On user "release": ```bash git checkout main && git pull git log --oneline -1 git tag ITER-{YYYYMMDD}-{slug} {merge_sha} gh release create "ITER-{YYYYMMDD}-{slug}" \ --target {merge_sha} \ --title "Iteration: {goal}" \ --notes "{approved_notes}" ``` ## Step 8: Close Milestone ```bash gh api repos/{owner}/{repo}/milestones/{N} -X PATCH -f state=closed ``` ## Artifacts Produced - Iteration Lessons Learned Document — `docs/lessons_learned/ITER-{YYYYMMDD}-{slug}.md`; consumed by Orient & Validate Scope (Activity 140) - Release Notes Draft — approved by human and published as the GitHub Release body ## Success Criteria - Graph execution record complete per issue - Validate Test Health (Activity 194) CRITICALs resolved; WARNINGs deferred as test-debt - Lessons Learned Document committed - SAO.md updated or sao-update issues filed - User explicitly approved merge; PR squash-merged; branch deleted - Tag points to merge commit on main - User explicitly approved release; GitHub Release created with --target {merge_sha} - Milestone closed ## Skill Skill 28 (Lessons Learned Writing) for Step 3. Skill 32 (GitHub Issue Operations) for Steps 6–8. ## Rules Follow Commit Convention (Rule [6]), Github Issues (Rule [14]), Small Increments (Rule [4])
Define Test Architecture	TFK-1	Test Automation Framework	Junior Edda	Inception (#1)	Read the 'TFK-1 Define Test Architecture' activity from playbook 'Junior Edda' (workflow 'Test Automation Framework'). Follow its guidance when assisting me. # Define Test Architecture ## Objective Consume DTA-06 "Define Test Strategy" decisions (already seeded into `docs/architecture/SAO.md` § Test Strategy) and flesh out that SAO section with the project's Test Trophy model, runner mapping, coverage policy, directory layout, and zero-bug / zero-length-feedback workflow. Authoritative output: update `docs/architecture/SAO.md` § Test Strategy. Do not treat a separate Test Architecture Document as the source of truth. A thin local pointer file (e.g. `docs/architecture/test-architecture.md` linking to SAO §5) is allowed for navigation only. Handoff: DTA-06 / DTA-18 write motivators and broad strokes. TFK-01 (run before BPE) completes directory layout, AT/E2E runner paths, and quality gates so construction can execute against a finished Test Strategy section. --- ## Decisions to Flesh Out in SAO.md ### 1. Test Trophy (not Pyramid) Our model is the Test Trophy — integration tests are the main bet: \| Level \| Weight \| Runner \| What it proves \| \|-------\|--------\|--------\|----------------\| \| Unit \| Thin \| pytest \| Custom queryset logic, pure utility functions, business logic methods — only where isolation adds value. Do NOT test default Model CRUD, auto-generated views, or framework behavior. \| \| Integration \| Thick \| pytest \| Feature works end-to-end with real DB, real services, real connections. No mocking. Think of them as acceptance tests minus the GUI. \| \| Acceptance (AT) \| Medium \| behave-django \| `.feature` scenarios in `docs/features/` executed against the app via Django test client. Steps from the TFK Step Library. BDD-grade executable requirements. \| \| E2E \| Selective \| behave + Playwright \| Full user journey in `tests/e2e/`. Sequential, slow, runs on staging before release. Screenshots for visual verification. \| ### 2. Why Test Trophy over Pyramid - Unit tests are limited: testing `model.save()` returns OK tells us nothing about whether data actually persisted - Acceptance tests with a real browser are expensive: slow, flaky - Integration tests hit the sweet spot: real thing, no GUI overhead, fast enough for CI - AT tests are integration tests with BDD syntax — the `.feature` file IS the requirements document made executable ### 3. Runner Mapping - pytest: everything up to and including integration tests - behave-django (`make test-at`): acceptance tests — `docs/features/` (spec + runner; Django test client; `tags = ~@wip`) - behave + Playwright (`make test-e2e`): E2E tests — `tests/e2e/` (LiveServer + browser; own `environment.py`) ### 4. Coverage Policy - Coverage metrics are necessary but not sufficient - Coverage is meaningless without quality — 90% coverage with useless tests is worse than 60% with real tests - Quality gates: no mocking in integration tests, no testing framework behavior, no tests > 10 lines without extraction - `@wip` scenarios excluded from CI; all other `docs/features/` scenarios must pass AT before merge ### 5. Zero-Bug and Zero-Length Feedback Document in SAO: bug = failing integration/AT scenario; fix same day with a permanent regression test; continuous pytest feedback via `tests.log`. ### 6. Agent test lanes When SAO §17 (AI Agent Architecture) applies — i.e. the project has agent workflows, tool registries, or LLM orchestration — extend the Test Strategy with a four-lane agent eval model. When SAO §17 is N/A (no agents), skip this subsection entirely; lanes 3–4 and agent Makefile targets are optional no-ops (see TFK-05). Four lanes: \| Lane \| Name \| Runner \| What it proves \| \|------\|------\|--------\|----------------\| \| 1 \| Control-plane proofs \| pytest `@agent_proof` + CAP-004 ScriptedLLM \| Orchestration: workflow id, tools offered/called, domain writes, plan/blackboard transitions — not model quality \| \| 2 \| Deterministic shell \| pytest integration (no LLM) \| D0 prefilter, JSON parse, validate-before-LLM, schema bounds — pure code paths \| \| 3 \| Live contract eval \| pytest `@live_llm` (nightly / optional CD) \| Provider contracts at temp=0: response shape, tool-call envelope, rate-limit handling \| \| 4 \| Task performance quality \| pytest `@quality` (promotion band) \| Frozen TASK-* golden tasks: structured oracle (recall, graph diff, schema bounds) \| Gate matrix (CI stage vs lane): \| Lane \| PR merge (`ci.yml`) \| Nightly (`agent-eval.yml`) \| Promotion / release \| \|------\|---------------------\|----------------------------\|---------------------\| \| 1 \| ✅ when `AGENTS_ENABLED=true` — `make test-agent-proof` \| — \| — \| \| 2 \| ✅ normal integration job (`make test-integration`) \| — \| — \| \| 3 \| ❌ not a PR gate \| ✅ scheduled / `workflow_dispatch` \| Optional CD cert when `AGENT_EVAL_ENABLED=true` \| \| 4 \| ❌ not a PR gate \| Optional regression run \| ✅ vs last certified pass band before promote \| PRF vs TASK (artifact 56): \| Artifact row \| Lane \| Assert helper \| Fixture root \| \|--------------\|------\|---------------\|--------------\| \| PRF-* (integration proof) \| 1 (+ lane 2 for non-LLM steps) \| `assert_agent_story(trace, …)` \| `tests/fixtures/llm_scripts/<prf-id>/` \| \| TASK-* (golden task) \| 4 \| structured oracle + optional domain asserts \| `tests/fixtures/agent_tasks/<task-id>/` \| PRF rows prove control plane under scripted LLM turns; TASK rows prove outcome quality under live (or promoted) models. Do not use lane 4 to prove 429 retry or HITL gates — those belong in PRF lane 1. Skip when SAO §17 N/A: If the project has no agent architecture section, do not add lane Makefile targets to required CI, do not block BPE/MIN on `agent_proof_command`, and do not create empty `llm_scripts/` / `agent_tasks/` trees. Artifact 11–13 templates add capability, not mandate. Document in SAO § Test Strategy: which PRF-* and TASK-* rows are in scope for this release, lane assignment, and `AGENTS_ENABLED` / `AGENT_EVAL_ENABLED` env conventions. --- ## Deliverables - ✅ SAO.md § Test Strategy fleshed out (Trophy, runners, paths, coverage, zero-bug, zero-length feedback) - ✅ SAO.md § Test Strategy § Agent lanes (when §17 applies): four-lane table, gate matrix, PRF vs TASK mapping, skip rules - ✅ Ready for TFK-02 Bootstrap Test Harness and BPE
Bootstrap Test Harness	TFK-2	Test Automation Framework	Junior Edda	Elaboration (#2)	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
Build Step Library	TFK-3	Test Automation Framework	Junior Edda	Elaboration (#2)	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.
Build Fixture Library	TFK-4	Test Automation Framework	Junior Edda	Elaboration (#2)	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.
Wire CICD Integration	TFK-5	Test Automation Framework	Junior Edda	Elaboration (#2)	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.
Establish E2E Infrastructure	TFK-6	Test Automation Framework	Junior Edda	Elaboration (#2)	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.
Add Step and/or Fixture to Library	TFK-7	Test Automation Framework	Junior Edda	Construction (#3)	Read the 'TFK-7 Add Step and/or Fixture to Library' activity from playbook 'Junior Edda' (workflow 'Test Automation Framework'). Follow its guidance when assisting me. # Add Step and/or Fixture to Library ## Objective On-demand activity invoked when ESM-05 "Write Feature Files" or BPE cannot assemble a scenario from existing steps/fixtures. Creates new reusable step definitions and/or fixtures following library conventions, then updates the catalogs. --- ## Trigger Called by other workflows when: 1. ESM-05 is writing a .feature and cannot find a matching step in the Step Library 2. BPE-04 needs a fixture preset that doesn't exist 3. A new domain area requires new step patterns 4. BPE-02 / MIN-04 declares a PRF-* row in SAO §17 but `tests/fixtures/llm_scripts/<prf-id>/` has no happy/reject script — add ScriptedLLM queue fixture(s) and catalog row (lane 1; pytest, not Gherkin) 5. DTA-19 / BPE adds a TASK-* golden row but `tests/fixtures/agent_tasks/<task-id>/` is missing input corpus, `expected.yaml`, or oracle `meta.yaml` — add frozen task fixture and catalog row (lane 4) 6. An existing PRF script needs a new reject_* variant (429, parse fail, HITL block, exhausted queue) per artifact 56 adverse sketch ## Process ### 1. Assess What's Needed - Identify the gap: missing step pattern, missing fixture, or both - Check if an existing step can be generalized/parameterized instead of creating a new one - For PRF/TASK triggers: confirm the gap is fixture/oracle catalog — not a missing Gherkin step (see TFK-03 footnote) ### 2. Create Step Definition (if needed) Follow library conventions: - Place in appropriate domain file (navigation, forms, tables, auth, assertions) - Use `data-testid` selectors - Parameterize generically - Log actions at INFO level Skip step creation when trigger is PRF script or TASK golden only. ### 3. Create Fixture (if needed) Follow library conventions: - JSON for static reference data → `tests/fixtures/presets/` - FactoryBoy for dynamic data → `tests/fixtures/factories/` - PRF ScriptedLLM queue → `tests/fixtures/llm_scripts/<prf-id>/` (`happy.json`, `reject_.json`) - TASK golden task* → `tests/fixtures/agent_tasks/<task-id>/` (`input/`, `expected.yaml`, `meta.yaml` per TFK-04 oracle schema) - Document scope and dependencies ### 4. Update Catalogs - Add new step to Step Library Catalog (GUI/AT only) - Add new fixture to Fixture Library Catalog - For agent fixtures: include `prf_id` / `task_id`, `oracle_type`, `pass_band`, `linked_test`, `sao_ref` ### 5. Verify - Write a small test scenario using the new step/fixture - Run it to verify it works - Ensure existing tests are not broken - PRF: run `pytest -m agent_proof` on the linked test; TASK: run `pytest -m quality` on the linked test (local or `agent-eval.yml` — not default PR until lane rules say so)
Validate Test Health	TFK-8	Test Automation Framework	Junior Edda	Construction (#3)	Read the 'TFK-8 Validate Test Health' activity from playbook 'Junior Edda' (workflow 'Test Automation Framework'). Follow its guidance when assisting me. # Validate Test Health ## Objective Periodic health check of the test suite: analyze coverage quality (not just quantity), flag anti-patterns, identify tests that need strengthening, and verify all test levels pass. --- ## Process ### 1. Run Coverage Analysis ```bash make test-coverage ``` Review coverage report, but remember: coverage is meaningless without quality. ### 2. Quality Audit — Flag Anti-Patterns Check for typical mistakes: Useless Tests: - Testing default Model methods (`model.save()`, `model.delete()`, `model.__str__()`) - Testing Django auto-generated views without custom logic - Tests that only check return codes without verifying side effects Testing Implementation, Not Behavior: - Test checks `save_changes()` returns OK but never verifies changes actually persisted - Test is tightly coupled to implementation details Fat Controller Signal: - Logic in views/controllers instead of services → tests are hard to write - Guideline: Services do the thinking → Views package and provide formatted data → Templates render it Mocking Violations: - Any mock/patch in integration tests → violation of no-mock rule ### 3. Verify All Test Levels Pass ```bash make test # unit + integration make test-at # acceptance make test-e2e # E2E (if staging available) ``` When SAO §17 applies: ```bash make test-agent-proof # lane 1 (when AGENTS_ENABLED=true) make test-agent-live # lane 3 (nightly / manual) make test-agent-quality # lane 4 (promotion band) ``` ### 4. Produce Health Summary Categorize findings as CRITICAL / WARNING / INFO. --- ## Agent eval health audit (when SAO §17 applies) Skip this subsection when SAO §17 is N/A. ### FakeLLM / ScriptedLLM script hygiene \| Check \| Severity \| Action \| \|-------\|----------\|--------\| \| FakeLLM or test double returns `[]` / empty string on queue exhaustion \| CRITICAL \| Replace with explicit raise; add `reject_exhausted` script variant \| \| Script turn count < PRF test's expected agent loop iterations \| WARNING \| Extend `llm_scripts/<prf-id>/happy.json` \| \| Live LLM used in `@agent_proof` test \| CRITICAL \| Move to `@live_llm` or switch to ScriptedLLM \| \| `assert_agent_story` beats missing for declared PRF row \| CRITICAL \| Add happy/reject test per rule `do-assert-agent-story` \| ### Tool / domain mocks in `@agent_proof` \| Check \| Severity \| Action \| \|-------\|----------\|--------\| \| `@patch` on ToolExecutor, broker, or domain service in `@agent_proof` \| CRITICAL \| Remove patch — lane 1 requires real DB + real tool registry \| \| Asserting assistant chat prose instead of trace beats \| WARNING \| Refactor to `assert_agent_story` control-plane keys \| \| Lane 2 deterministic test uses ScriptedLLM \| INFO \| Use plain pytest — no LLM for D0/parse/validate \| Carve-out: only CAP-004 ScriptedLLM may stand in for the LLM in integration tests (rule `do-not-mock-in-integration-tests` ALTER). ### PRF coverage vs SAO §17 Build a matrix from SAO §17 PRF checkbox table vs repo: \| SAO §17 PRF row \| `llm_scripts/` present \| `@agent_proof` test \| happy + reject \| Status \| \|-----------------\|------------------------\|---------------------\|----------------\|--------\| \| e.g. PRF-SC01-04 \| yes/no \| yes/no \| yes/no \| PASS / GAP \| CRITICAL gaps: in-scope PRF row with no linked test or missing reject variant when artifact 56 marks adverse. WARNING gaps: test exists but catalog row in Fixture Library missing `sao_ref` / `linked_test`. ### TASK coverage vs SAO §17 (lane 4) \| SAO §17 TASK row \| `agent_tasks/` oracle \| `@quality` test \| pass_band documented \| Status \| \|------------------\|----------------------\|-----------------\|----------------------\|--------\| \| e.g. TASK-SC02-01 \| yes/no \| yes/no \| yes/no \| PASS / GAP \| Lane 4 gaps are WARNING until promotion window — do not fail PR CI for missing TASK tests. Include agent audit findings in the TAF-08 health summary with lane tags (L1–L4) for TFK-09 scoreboard input.
Prepare Test Report	TFK-9	Test Automation Framework	Junior Edda	Construction (#3)	Read the 'TFK-9 Prepare Test Report' activity from playbook 'Junior Edda' (workflow 'Test Automation Framework'). Follow its guidance when assisting me. # Prepare Test Report ## Objective Analyze test coverage, last run results, and TAF-08 health findings to produce an actionable test report. Outcomes are turned into GitHub Issues assigned for implementation — closing the feedback loop between test health and development work. --- ## Process ### 1. Gather Inputs - TAF-08 "Validate Test Health" findings - Last CI/CD run results (pass/fail per stage, duration, flaky test history) - E2E screenshot archive - `tests.log` analysis When SAO §17 applies, also gather: - Last `agent-eval.yml` run (lanes 3–4): pass/fail, provider, model pin, duration - Lane 1 PR `test-agent-proof` history when `AGENTS_ENABLED=true` - TFK-08 PRF/TASK coverage matrix vs SAO §17 ### 2. Analyze Coverage Gaps For each area with insufficient coverage: - Identify which scenarios from .feature files lack corresponding tests - Identify services/methods with zero or low coverage - Assess risk and prioritize For agent projects: cross-check SAO §17 PRF/TASK rows against green tests (TFK-08 matrix). ### 3. Analyze Quality Issues \| Category \| Examples \| Issue Type \| \|----------\|----------\|------------\| \| Missing tests \| Service method with no test \| Scenario issue \| \| Weak tests \| Tests check return code but not side effects \| Enhancement issue \| \| Fat controllers \| Logic in views needing extraction \| Refactoring issue \| \| Mocking violations \| Mocks in integration tests \| Bug issue \| \| Flaky tests \| Non-deterministic pass/fail \| Bug issue \| \| Agent proof gaps \| PRF row unchecked vs repo \| Scenario issue (lane 1) \| \| FakeLLM hygiene \| Silent queue exhaustion \| Bug issue (lane 1) \| \| Task band regression \| recall below certified pass_band \| Enhancement issue (lane 4) \| ### 4. Produce Report and Create Issues For each finding, create a GitHub Issue with: - What: specific test/file/scenario that needs work - Why: what risk the gap exposes - How: concrete action - Effort: easy/medium/hard - Priority: critical/important/nice-to-have --- ## Agent eval scoreboard (lanes 3 & 4) When SAO §17 applies, append a Lane 3/4 scoreboard section to the test report. Omit when agents N/A. ### Lane 3 — Live contract eval \| Run id \| Date \| Provider / model \| Tests run \| Pass \| Fail \| Flake \| Notes \| \|--------\|------\|------------------\|-----------\|------\|------\|-------\|-------\| \| … \| … \| e.g. anthropic/claude-* \| `@live_llm` count \| \| \| \| temp=0; contract asserts only \| Track: tool-call envelope shape, rate-limit handling, timeout bounds. Not a merge gate — trend for infra/prompt regressions before promotion. ### Lane 4 — Task performance quality \| Task id \| Oracle type \| Pass band \| Last N runs \| Recall / metric \| Extras \| Certified \| vs prior cert \| \|---------\|-------------\|-----------\|-------------\|-----------------\|--------\|-----------\|---------------\| \| TASK-SC02-01 \| set_recall \| ≥0.95, extras≤1 \| 3 \| 0.97 \| 0 \| ✅ \| +0.02 \| Certification rule: promote only when all in-scope TASK rows meet `pass_band` for `n_runs` consecutive evals at temp=0. Regression vs last certified band → open GitHub Issue (priority: important) with task id and metric delta. ### Combined agent summary (for PIN / release notes) \| Lane \| CI home \| Last green \| Open gaps (from TFK-08) \| Release impact \| \|------\|---------\|------------\|---------------------------\|----------------\| \| 1 PRF \| optional PR step \| … \| … \| blocks merge if enabled + red \| \| 2 shell \| `ci.yml` integration \| … \| … \| blocks merge \| \| 3 contract \| `agent-eval.yml` \| … \| … \| advisory / optional CD \| \| 4 quality \| promotion band \| … \| … \| blocks promote if cert required \| Production signals (outside pytest): optionally note HITL reject rate, edit-before-approve ratio, learning-rule growth — feeds PIN-02; reference skill Agent Task Eval § Production quality. Feed scoreboard CRITICAL/WARNING rows into §4 issue creation with labels `agent-lane-3`, `agent-lane-4`, or `agent-prf-gap` as appropriate.
Determine Cadence & Iteration Length	RIN-1	Run the Iteration	Junior Edda	Construction (#3)	Read the 'RIN-1 Determine Cadence & Iteration Length' activity from playbook 'Junior Edda' (workflow 'Run the Iteration'). Follow its guidance when assisting me. ## Objective Choose the iteration length and collaboration cadence from current team evidence, then record the decision in `docs/project/iterations/<iteration_id>/ITERATION_FRAME.md`. ## Required inputs - Approved `docs/project/CHARTER.md`, especially Team Roster, maturity classification, and maturity evidence. - Delivery Management Assignment. - Candidate start date and participant availability. ## Procedure 1. Enter the ADE's planning mode when available; otherwise write the execution plan before changing project state. 2. Validate the Charter's maturity assessment. If it is missing or older than one completed iteration, reassess it with the Delivery Manager and team and update the Charter before selecting cadence. 3. Apply the default mapping: - `L2` or `early-L3`: one-week iteration. - `late-L3` or `L4`: one-day iteration. 4. A different length is allowed only when the Delivery Manager records evidence and an expiry/review date. 5. For a one-person team, omit recurring meeting overhead; use asynchronous records and decision points. For larger teams, name only the ceremonies needed for coordination. 6. Create a stable `iteration_id` and record start/end timestamps, maturity/evidence, chosen length, ceremonies/triggers, participants, timezone, exception rationale, and approval. ## Completion evidence The frame exists, the maturity evidence is current, the selected length is mechanically derived or explicitly justified, every ceremony has a purpose and owner, and the Delivery Manager approval is recorded.
Set the Iteration Goal	RIN-2	Run the Iteration	Junior Edda	Construction (#3)	Read the 'RIN-2 Set the Iteration Goal' activity from playbook 'Junior Edda' (workflow 'Run the Iteration'). Follow its guidance when assisting me. ## Objective Select one outcome that can be accepted within the iteration frame and make its evidence and exclusions explicit. ## Required inputs - Iteration Frame. - Charter goals and gating policies. - Ordered product/delivery backlog. - Previous Iteration Assessment Report, open Risk/Problem tickets, and accepted/deferred IIPs when available. - Current capacity and known dependencies. ## Procedure 1. Review gating tickets first. A `pause_new_work` concern prevents dispatch of new delivery work; a `block_release` concern must be resolved or explicitly waived by the authorized human before release. 2. Select one outcome, not a list of unrelated tasks. 3. State: beneficiary, behavior/result, quantitative or observable success measure, acceptance evidence, excluded scope, dependencies, owner, and why it fits the chosen length. 4. Link each included concern or backlog item. Do not silently absorb work discovered during assessment. 5. Update the Iteration Frame with the goal and obtain Delivery Manager/team commitment. ## Completion evidence The frame contains one bounded goal, objective acceptance evidence, explicit exclusions, dependency owners, ticket-gate disposition, and approval. If the goal cannot fit, reduce it before invoking PIN.
Plan the Iteration	RIN-3	Run the Iteration	Junior Edda	Construction (#3)	Read the 'RIN-3 Plan the Iteration' activity from playbook 'Junior Edda' (workflow 'Run the Iteration'). Follow its guidance when assisting me. ## Objective Invoke Plan the Iteration (PIN) for the approved goal and produce an accepted, executable delivery manifest. ## Procedure 1. Pass PIN the Iteration Frame, Charter, relevant architecture/process context, open gating tickets, and accepted IIPs. 2. Follow PIN's own activity order and planning rules. Enter enforced ADE planning mode when available. 3. Fan out bounded investigation only where PIN permits and only when workers have distinct outputs or read-only scopes. 4. Converge estimates, dependencies, codebase footprints, checkpoints, parallel groups, and human gates into one manifest/milestone. 5. Obtain the PIN approval required before execution. ## Failure handling Do not invoke MIN with a speculative, internally inconsistent, or unapproved plan. If planning reveals that the goal does not fit, return to Set the Iteration Goal and narrow it. ## Completion evidence The accepted PIN output names every scenario/work item, dependency, codebase footprint, checkpoint command, time budget, parallel group, and approval gate. Its goal and iteration ID match the Iteration Frame.
Execute the Iteration	RIN-4	Run the Iteration	Junior Edda	Construction (#3)	Read the 'RIN-4 Execute the Iteration' activity from playbook 'Junior Edda' (workflow 'Run the Iteration'). Follow its guidance when assisting me. ## Objective Execute the approved manifest through Manage the Iteration (MIN) while Assess the Iteration (AIN) observes independently. ## Procedure 1. Invoke MIN with the accepted PIN output; do not re-plan it inside this activity. 2. When MIN begins, trigger AIN as a separate/background stream against the same project and iteration ID. If the ADE supports subagents or parallel tasks, isolate AIN from delivery-worker contexts. Otherwise schedule AIN checkpoints without blocking independent delivery work. 3. MIN owns delivery dispatch, checkpoints, drift, integration, and its human gates. AIN owns measurement, ticket lifecycle, throughput, coverage, and its final assessment report. 4. Apply the latest assessment signals: - `observe`: record and continue. - `pause_new_work`: finish safe in-flight checkpoints but dispatch no new work until resolved/waived. - `block_release`: continue safe work but do not release until resolved/waived. 5. Never let AIN edit the MIN manifest or production code. Never let MIN mark an assessment concern Green without AIN evidence. 6. Preserve all required human approvals for scope, merge, release, purchase, or external side effects. ## Completion evidence MIN reaches an explicit complete/escalated state; every checkpoint result and drift decision is recorded; the latest AIN run is complete or explicitly pending; gating signals were enforced; and any shipped increment has verified acceptance and release evidence.
Hold the Iteration Retrospective	RIN-5	Run the Iteration	Junior Edda	Construction (#3)	Read the 'RIN-5 Hold the Iteration Retrospective' activity from playbook 'Junior Edda' (workflow 'Run the Iteration'). Follow its guidance when assisting me. ## Objective Convert the iteration's delivery and assessment evidence into owned learning without rewriting history. ## Required inputs - Iteration Frame and accepted PIN/MIN records. - Release/acceptance evidence. - Latest complete Iteration Assessment Report and Project-Management Tickets. - Charter and participants named in its Team Roster. ## Procedure 1. Create `docs/project/retros/<iteration_id>.md`. 2. Compare planned versus actual outcome, duration, throughput, quality, coordination, and assessment signals. 3. For each material variance, record evidence, causal hypothesis, impact, and whether it is: - a product/code/delivery concern to track as backlog or Risk/Problem ticket; or - a repeatable process concern eligible for an IIP. 4. Record decisions, action owners, due dates, and experiments. Do not turn every complaint into a process change. 5. Reassess team maturity only when the iteration produced relevant evidence; update the Charter with evidence and date, not intuition. ## Completion evidence The retrospective cites source records, separates fact from interpretation, classifies each concern, assigns every accepted action, records unchanged/open questions, and has participant acknowledgment.
Raise Iteration Improvement Proposals	RIN-6	Run the Iteration	Junior Edda	Construction (#3)	Read the 'RIN-6 Raise Iteration Improvement Proposals' activity from playbook 'Junior Edda' (workflow 'Run the Iteration'). Follow its guidance when assisting me. ## Objective Let any delivery participant propose a bounded change to Junior Edda or its project-specific application. The Delivery Manager facilitates and records; the team—not the Delivery Manager alone—authors proposals. ## Procedure 1. Review the retrospective, MIN drift/escalations, AIN report, and repeated Project-Management Tickets. 2. Create an IIP only for a repeatable process defect or improvement opportunity. Product defects and one-off project work remain tickets/backlog items. 3. Search open IIPs for the same concern; update or link an existing proposal instead of duplicating it. 4. Write each proposal to `docs/project/iips/<iip_id>-<slug>.md` with: - stable IIP ID and title; - author(s), affected workflow/activity/rule/artifact; - problem and evidence; - proposed change; - expected effect and measurement; - compatibility/migration impact; - owner and decision point; - status: `proposed \| accepted \| rejected \| deferred \| implemented`. 5. Do not edit released Junior Edda directly. Route accepted playbook changes through the applicable governance/PIP mechanism. ## Completion evidence Every IIP has evidence, a bounded change, affected objects, an owner, decision point, status, and duplicate check. It is acceptable to record “no IIP warranted” with rationale.
Prepare the Next Iteration	RIN-7	Run the Iteration	Junior Edda	Construction (#3)	Read the 'RIN-7 Prepare the Next Iteration' activity from playbook 'Junior Edda' (workflow 'Run the Iteration'). Follow its guidance when assisting me. ## Objective Close the current iteration cleanly and leave an evidence-based entry condition for the next one. ## Required inputs Iteration Frame, retrospective, IIPs, Project-Management Tickets, latest AIN report, Charter, backlog, and release evidence. ## Procedure 1. Disposition every IIP as accepted, rejected, deferred, or still under review; name owner and decision date. 2. Update the Charter only for approved changes to goals, ownership, maturity, variables, artifact coverage, cadence, or roadmap. Add a dated change log. 3. Carry forward open Risk/Problem tickets with current evidence and gating policy; do not duplicate them. 4. Record a short ordered list of candidate next goals, dependencies, capacity constraints, and mandatory ticket work. 5. Close the current Iteration Frame with actual end time, result, release identifier, assessment report, and unresolved concerns. 6. State the next-entry condition. Do not automatically start a new iteration or pre-authorize its goal. ## Completion evidence The current frame is closed; Charter changes are approved and versioned; every IIP/ticket has a disposition or owner; candidate goals are ordered but not falsely committed; and the next RIN run can begin from the recorded entry condition.
Open an Assessment Run	AIN-1	Assess the Iteration	Junior Edda	Construction (#3)	Read the 'AIN-1 Open an Assessment Run' activity from playbook 'Junior Edda' (workflow 'Assess the Iteration'). Follow its guidance when assisting me. ## Objective Create one traceable, immutable assessment snapshot without interfering with delivery work. ## Required inputs - Project Charter and Delivery Management Assignment. - Huginn Assessment Contract. - Project/repository/environment identity and the current iteration ID when one exists. ## Procedure 1. Validate that every tracked Charter variable has a stable `variable_id`, source, exact query/command, window, freshness limit, bands, Unknown behavior, owner, and gating policy. 2. Acquire the project assessment lock. If another run is active, return its run ID or wait according to the Huginn contract; never create overlapping side effects. 3. Create `run_id = AIN-<UTC timestamp>` and directory `docs/project/assessments/<run_id>/`. 4. Establish one snapshot boundary: repository revision, environment, iteration ID, source-system timestamps/cursors, Charter version, and artifact inventory timestamp. 5. Write `RUN.md` with trigger, initiator, timestamps, inputs, snapshot identifiers, expected outputs, lock state, and status `running`. 6. Freeze the snapshot for this run. Later source changes belong to the next run. ## Safety This activity is read-only except for the Assessment Run Record and lock. It does not modify the delivery manifest, code, Charter, tickets, or deployment. ## Completion evidence A unique run directory and record exist; input versions and snapshot boundary are reproducible; one-run-at-a-time behavior is demonstrated; and downstream activities can reference the same run ID.
Assess Charter Variables	AIN-2	Assess the Iteration	Junior Edda	Construction (#3)	Read the 'AIN-2 Assess Charter Variables' activity from playbook 'Junior Edda' (workflow 'Assess the Iteration'). Follow its guidance when assisting me. ## Objective Measure every Charter variable from the run snapshot and produce evidence; do not create or update tickets here. ## Procedure 1. Read the variable contracts from the Charter version recorded in `RUN.md`. 2. If the ADE supports parallel workers, fan out one bounded worker per variable (or per non-overlapping source batch). Every worker is read-only and writes only `variables/<variable_id>.json`; no two workers share an output file or ticket key. 3. For each variable execute the exact declared query/command and record: - `variable_id`, definition, unit, source, query/command, window; - raw result or bounded evidence reference; - observed timestamp and source timestamp; - freshness and validation result; - current value; - prior and current band: `Green \| Yellow \| Orange \| Red \| Unknown`; - threshold calculation and owner; - measurement error, if any. 4. Missing, stale, inaccessible, malformed, or non-reproducible evidence is `Unknown`, never Green. Apply the Charter's declared Unknown policy without inventing a value. 5. After all workers finish, validate schema and coverage and produce `VARIABLE_RESULTS.json` sorted by stable variable ID. ## Completion evidence There is exactly one valid result per Charter variable; all results use the same run ID/snapshot; failures are explicit Unknowns; raw provenance is retained; and no ticket or delivery state was mutated.
Reconcile Risk and Problem Tickets	AIN-3	Assess the Iteration	Junior Edda	Construction (#3)	Read the 'AIN-3 Reconcile Risk and Problem Tickets' activity from playbook 'Junior Edda' (workflow 'Assess the Iteration'). Follow its guidance when assisting me. ## Objective Apply the measured variable results to a stable, idempotent Risk/Problem ticket lifecycle. ## Procedure 1. Load `VARIABLE_RESULTS.json` and the configured GH/Jira adapter. 2. For each variable derive `concern_key = <project_id>:<variable_id>`. 3. Fan out read-only ticket lookup if useful, then serialize all creates/updates/closes per `concern_key`. Never let two workers mutate the same concern. 4. Apply this state machine: - Green with no open concern: no action. - Yellow/Orange: create or update one Risk ticket. - Red: create or update one Problem ticket; convert the same concern when the adapter supports type change, otherwise link/close the old representation atomically. - Unknown: never close or green a concern. Create/update the same concern as a measurement-health Risk unless the Charter declares a stricter treatment. - Return to Green: resolve the open concern only with fresh Green evidence. 5. On Yellow↔Orange, band changes, new evidence, changed severity, or gating-policy changes, update the existing ticket even when its type does not change. 6. Use `<run_id>:<variable_id>` as the idempotency key. Retry must yield the same ticket and action record. 7. Emit `TICKET_ACTIONS.json` with prior/new state, action, ticket ID/URL, evidence, gating policy, and errors. ## Failure handling A ticket-adapter failure does not erase the measurement. Mark the action failed, keep the run incomplete, and retry idempotently. Never create a substitute duplicate. ## Completion evidence Every non-Green/Unknown variable has exactly one stable concern; lifecycle changes reflect evidence; gating signals are explicit; and a repeated run/retry creates no duplicate ticket.
Measure Delivery Throughput	AIN-4	Assess the Iteration	Junior Edda	Construction (#3)	Read the 'AIN-4 Measure Delivery Throughput' activity from playbook 'Junior Edda' (workflow 'Assess the Iteration'). Follow its guidance when assisting me. ## Objective Measure accepted delivery flow from the same assessment snapshot independently of variable assessment and ticket mutation. ## Procedure 1. Use the iteration ID, repository revision, and source cursors from `RUN.md`. 2. Read the authoritative delivery records declared in the Huginn contract (for example accepted scenario issues, merged changes, releases, and acceptance checks). 3. Count completed accepted items in the declared cadence/window. Also record cycle time and work-in-progress when the source supports them. 4. Story points are optional and must not replace item throughput unless the Charter explicitly defines their source and use. 5. Exclude reopened, rejected, duplicate, or unaccepted work and record the exclusion reason. 6. Write `THROUGHPUT.json` with window, sources/queries, counts, item IDs, exclusions, cycle-time summary, WIP, freshness, and errors. ## Completion evidence The result is reproducible from named records, uses the run snapshot and cadence window, distinguishes accepted work from activity volume, and expresses missing/stale data as Unknown rather than zero.
Assess Required-Artifact Coverage	AIN-5	Assess the Iteration	Junior Edda	Construction (#3)	Read the 'AIN-5 Assess Required-Artifact Coverage' activity from playbook 'Junior Edda' (workflow 'Assess the Iteration'). Follow its guidance when assisting me. ## Objective Verify the existence, validity, ownership, and freshness of every artifact the Charter marks required. ## Procedure 1. Read the required-artifact table from the Charter version in `RUN.md`. 2. If the ADE supports parallel workers, fan out one read-only worker per artifact. Each writes only `artifacts/<artifact_id>.json`. 3. For each artifact check its declared canonical path/system, validation command or schema, owner, version, freshness rule, and expected producer. 4. Record `present \| missing \| stale \| invalid \| inaccessible`; never infer coverage from a similarly named file. 5. Converge results into `ARTIFACT_COVERAGE.json` with covered/required counts, percentage when meaningful, missing/invalid list, evidence locations, and errors. 6. Do not create missing artifacts in this workflow; route remediation to RIN/backlog or a Project-Management Ticket according to Charter policy. ## Completion evidence Every required artifact has one evidence-backed status from the shared snapshot; validation was executed where declared; gaps have owners or routing; and coverage is not overstated.
Converge Assessment & Publish Report	AIN-6	Assess the Iteration	Junior Edda	Construction (#3)	Read the 'AIN-6 Converge Assessment & Publish Report' activity from playbook 'Junior Edda' (workflow 'Assess the Iteration'). Follow its guidance when assisting me. ## Objective Join all assessment branches, publish one complete supervisory verdict, and release the project assessment lock. ## Required inputs For the same run ID: Assessment Run Record, Variable Assessment Evidence, Ticket Action Record, Delivery Throughput Snapshot, and Required-Artifact Coverage Report. ## Procedure 1. Verify every required input exists, validates, and uses the same run ID, Charter version, iteration ID, and snapshot boundary. 2. If any branch is missing, stale, schema-invalid, or has an unresolved side-effect error, mark the run `incomplete`; do not publish a success verdict or release an ambiguous partial report. 3. Create `ITERATION_ASSESSMENT.md` containing: - run/snapshot identity and input versions; - executive verdict: `Green \| Yellow \| Orange \| Red \| Unknown`; - per-variable prior/current band, evidence, ticket action, owner, and gating policy; - throughput and cycle-time findings; - artifact-coverage findings; - active `observe \| pause_new_work \| block_release` signals; - required next actions with owner and due/decision point; - errors, Unknowns, and confidence/provenance limitations. 4. Derive the overall verdict from declared Charter policy. Never average away a Red, Unknown, or gating signal. 5. Update `RUN.md` to `complete` with output checksums/links and end time; release the lock. 6. Notify the Delivery Manager and the RIN/MIN execution context through the destinations in the Huginn contract. ## Completion evidence The report is reproducible, internally consistent, complete for all branches, explicit about Unknowns and gates, linked to stable tickets, and the run record is complete with the lock released.
Identify source type	PIN-1	Prepare for Ingestion	Playbook for Playbooks	Source Characterization (#1)	Read the 'PIN-1 Identify source type' activity from playbook 'Playbook for Playbooks' (workflow 'Prepare for Ingestion'). Follow its guidance when assisting me. Classify the source type AND sub-type: Book: methodology (process-focused), reference (lookup-focused), narrative (story-focused) Scientific paper: methods (new technique), survey (literature review), empirical (measurement study), position (argument/opinion) Personal notes: how-to (procedural), reflective (lessons learned), reference (collected facts) The sub-type drives extraction heuristics downstream: methods papers concentrate process in the Method section; surveys require cross-source synthesis; empirical papers have process in experimental design; books tend to have explicit roles and artifacts; notes embed goals in prose.
Assess structure	PIN-2	Prepare for Ingestion	Playbook for Playbooks	Source Characterization (#1)
Assess explicitness	PIN-3	Prepare for Ingestion	Playbook for Playbooks	Source Characterization (#1)	Read the 'PIN-3 Assess explicitness' activity from playbook 'Playbook for Playbooks' (workflow 'Prepare for Ingestion'). Follow its guidance when assisting me. Identify what is explicit (named roles, defined steps, listed outputs) vs. implicit (assumed knowledge, undocumented actors, unstated constraints). Capture findings in an "Implicit Items" section at the top of the Extraction Worksheet: - What roles/agents are assumed but unnamed? - What prerequisite knowledge or tools are assumed? - What constraints are implied but not stated? These flags prime the EKN extraction steps — implicit items need active inference, not just transcription. Without this record they evaporate between PIN and EKN.
Segment source	PIN-4	Prepare for Ingestion	Playbook for Playbooks	Source Characterization (#1)
Extract goals	EEN-1	Extract Knowledge	Playbook for Playbooks	Semantic Extraction (#2)
Extract activities	EEN-2	Extract Knowledge	Playbook for Playbooks	Semantic Extraction (#2)
Extract agents	EEN-3	Extract Knowledge	Playbook for Playbooks	Semantic Extraction (#2)	Read the 'EEN-3 Extract agents' activity from playbook 'Playbook for Playbooks' (workflow 'Extract Knowledge'). Follow its guidance when assisting me. Identify all roles, actors, and responsible parties. Where roles are implicit, use source-type heuristics: - Book/notes: define at minimum the practitioner role (the person following the playbook) - Scientific paper: roles are almost always implicit — infer from who would implement the method (e.g. ML Engineer, Data Engineer, Researcher). Only add agents if they meaningfully differentiate who does what. If all activities would have the same agent, consider omitting agents entirely — undifferentiated agents add no value and create noise.
Extract skills	EEN-4	Extract Knowledge	Playbook for Playbooks	Semantic Extraction (#2)
Extract artifacts	EEN-5	Extract Knowledge	Playbook for Playbooks	Semantic Extraction (#2)
Extract rules	EEN-6	Extract Knowledge	Playbook for Playbooks	Semantic Extraction (#2)
Review worksheet	EEN-7	Extract Knowledge	Playbook for Playbooks	Semantic Extraction (#2)	Read the 'EEN-7 Review worksheet' activity from playbook 'Playbook for Playbooks' (workflow 'Extract Knowledge'). Follow its guidance when assisting me. Human reviews the full Extraction Worksheet. Resolve ambiguities, fill gaps, and validate that nothing significant was missed. Every item must include a source reference (chapter, section, page, bullet). Produce the final Extraction Worksheet artifact.
Map goals to hierarchy	AAP-1	Assemble Playbook	Playbook for Playbooks	Ontology Assembly (#3)
Group activities into workflows	AAP-2	Assemble Playbook	Playbook for Playbooks	Ontology Assembly (#3)	Read the 'AAP-2 Group activities into workflows' activity from playbook 'Playbook for Playbooks' (workflow 'Assemble Playbook'). Follow its guidance when assisting me. Cluster activities into coherent sequences that share a defined output. Assign each workflow a name, 3-letter abbreviation, and description. Grouping heuristics: - Pipeline stage: what triggers the next group? (data prep → model → evaluation is a natural boundary) - Shared artifact: activities that produce and consume the same intermediate artifact belong together - Role boundary: if a different skill or team takes over, that is often a workflow boundary - Size check: prefer 3–7 activities per workflow — fewer suggests over-splitting; more suggests under-splitting
Group workflows into phases	AAP-3	Assemble Playbook	Playbook for Playbooks	Ontology Assembly (#3)
Wire predecessors	AAP-4	Assemble Playbook	Playbook for Playbooks	Ontology Assembly (#3)
Link agents, skills, artifacts, rules	AAP-5	Assemble Playbook	Playbook for Playbooks	Ontology Assembly (#3)
Validate coverage	AAP-6	Assemble Playbook	Playbook for Playbooks	Ontology Assembly (#3)
Create in Mimir	AAP-7	Assemble Playbook	Playbook for Playbooks	Ontology Assembly (#3)	Read the 'AAP-7 Create in Mimir' activity from playbook 'Playbook for Playbooks' (workflow 'Assemble Playbook'). Follow its guidance when assisting me. Build the playbook in Mimir using the MCP tools. Create phases first, then workflows, then activities in order. Wire all links: agents, skills, artifacts, rules, and predecessors. Verify the final structure matches the validated worksheet. This is not the release gate — next is Run intern test.
Run intern test	AAP-8	Assemble Playbook	Playbook for Playbooks	Ontology Assembly (#3)	Read the 'AAP-8 Run intern test' activity from playbook 'Playbook for Playbooks' (workflow 'Assemble Playbook'). Follow its guidance when assisting me. Hand the assembled Mimir playbook to a capable intern or coding agent who has never seen this domain. Give them one activity at a time: name, guidance, and that activity's linked skills, artifacts, rules, and agent. No briefing, no extra files, no Extraction Worksheet. They must answer: from this packet alone, can I tell what needs to be done, or at least find pointers to the pieces I need to put together? Sample at least one activity per workflow, including the hardest assembly step — not only the easy ones. Record pass/fail and the intern's exact stuck-point in Intern Test Report. Pass: they can start without asking what the playbook is about, where inputs live, or which other work they must invent. Fail: they need tribal knowledge. Fix the activity (guidance and links), then re-test that activity. Do not release until the sample passes.
Extract variable usage slots	CSE-1	Collect and Compile Source	Program Graphs for Code Analysis	Data Preparation (#1)	Read the 'CSE-1 Extract variable usage slots' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Collect and Compile Source'). Follow its guidance when assisting me. For each variable usage location (excluding declarations), check that at least one other type-compatible variable is in scope. Each such location becomes a training slot. Record the ground-truth variable at each slot.
Filter compilable projects	CSE-1	Collect and Compile Source	Program Graphs for Code Analysis	Data Preparation (#1)
Scrape target repositories	CSE-1	Collect and Compile Source	Program Graphs for Code Analysis	Data Preparation (#1)
Split dataset by file	CSE-1	Collect and Compile Source	Program Graphs for Code Analysis	Data Preparation (#1)	Read the 'CSE-1 Split dataset by file' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Collect and Compile Source'). Follow its guidance when assisting me. Partition into train/validation/test splits along source file boundaries — all examples from one file must go to the same split. Reserve held-out projects (no files in training) for UNSEENPROJTEST evaluation. Suggested split: 60-10-30.
Add backward edges	BGS-1	Build Program Graphs	Program Graphs for Code Analysis	Data Preparation (#1)	Read the 'BGS-1 Add backward edges' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Build Program Graphs'). Follow its guidance when assisting me. For every edge type added (Child, NextToken, LastRead, LastWrite, ComputedFrom, LastLexicalUse, ReturnsTo, FormalArgName), add the corresponding backward edge by transposing the adjacency matrix. This doubles edge count and types, aids information propagation, and increases model expressiveness.
Add semantic shortcut edges	BGS-1	Build Program Graphs	Program Graphs for Code Analysis	Data Preparation (#1)	Read the 'BGS-1 Add semantic shortcut edges' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Build Program Graphs'). Follow its guidance when assisting me. Add LastLexicalUse edges chaining all occurrences of the same variable (independent of data flow). Add ReturnsTo edges connecting return tokens to their method declaration. Add FormalArgName edges connecting call-site arguments to the formal parameter names they map to.
Parse source to AST	BGS-1	Build Program Graphs	Program Graphs for Code Analysis	Data Preparation (#1)	Read the 'BGS-1 Parse source to AST' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Build Program Graphs'). Follow its guidance when assisting me. Parse each source file to its Abstract Syntax Tree. Label syntax nodes with nonterminal names and syntax tokens with their string representation. Add Child edges connecting parent-child AST relationships and NextToken edges connecting consecutive tokens.
Add data flow edges	BGS-1	Build Program Graphs	Program Graphs for Code Analysis	Data Preparation (#1)	Read the 'BGS-1 Add data flow edges' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Build Program Graphs'). Follow its guidance when assisting me. For each variable token v, compute DR(v) (last read locations) and DW(v) (last write locations). Add LastRead and LastWrite edges accordingly — these may span non-sequential locations including across loop boundaries. Add ComputedFrom edges connecting assignment targets to all variable tokens in the right-hand side expression.
Compute type hierarchy embeddings	CRS-1	Compute Node Representations	Program Graphs for Code Analysis	Data Preparation (#1)	Read the 'CRS-1 Compute type hierarchy embeddings' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Compute Node Representations'). Follow its guidance when assisting me. For each variable, collect the full set of its supertypes (type lattice τ(v)). Learn an embedding r(τ) for each known type; use "UNKTYPE" for unseen types. Compute the variable's type representation as the element-wise maximum over {r(τ) : τ ∈ τ(v)}. During training, randomly sample a non-empty subset of τ*(v) as regularization.
Compute subtoken embeddings	CRS-1	Compute Node Representations	Program Graphs for Code Analysis	Data Preparation (#1)	Read the 'CRS-1 Compute subtoken embeddings' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Compute Node Representations'). Follow its guidance when assisting me. Split each node name on camelCase and pascal_case boundaries into subtokens (e.g. classTypes → [class, types]). Learn an embedding for each subtoken. Compute the node name embedding as the average of its subtoken embeddings.
Assemble initial node state	CRS-1	Compute Node Representations	Program Graphs for Code Analysis	Data Preparation (#1)
Run GGNN propagation	TGN-1	Train GGNN	Program Graphs for Code Analysis	Model Training (#2)	Read the 'TGN-1 Run GGNN propagation' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Train GGNN'). Follow its guidance when assisting me. For each step: compute messages m(v)_k = linear(h(v)) per edge type. Aggregate incoming messages via elementwise summation. Update node state via GRU: h'(v) = GRU(aggregated_messages, h(v)). Repeat for exactly 8 steps — fewer is insufficient; more does not help.
Configure task-specific graph	TGN-1	Train GGNN	Program Graphs for Code Analysis	Model Training (#2)	Read the 'TGN-1 Configure task-specific graph' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Train GGNN'). Follow its guidance when assisting me. For VARNAMING: replace all tokens of the target variable with a special SLOT token. For VARMISUSE: insert a v_SLOT node at the target location connected via all non-variable edges; insert candidate nodes v_t,v for each type-compatible variable connected via LastUse, LastWrite, LastLexicalUse edges. Set an extra bit to 1 for candidate nodes.
Batch graphs as disconnected components	TGN-1	Train GGNN	Program Graphs for Code Analysis	Model Training (#2)	Read the 'TGN-1 Batch graphs as disconnected components' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Train GGNN'). Follow its guidance when assisting me. Represent each graph as a sparse adjacency list to minimize memory. Combine a minibatch into one large graph with disconnected components by making node IDs unique per batch. Prepare minibatches on a separate CPU thread to avoid GPU stalls during training.
Train with maximum likelihood	TGN-1	Train GGNN	Program Graphs for Code Analysis	Model Training (#2)	Read the 'TGN-1 Train with maximum likelihood' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Train GGNN'). Follow its guidance when assisting me. VARNAMING: average final SLOT node states; use as GRU initial state to predict variable name as subtoken sequence via MLE. VARMISUSE: compute context c(t)=h(v_SLOT) and usage u(t,v)=h(v_t,v); train argmax of c(t)^T u(t,v) via MLE. Report accuracy (exact match) and F1 (subtoken match) for VARNAMING; accuracy and PR-AUC for VARMISUSE.
Evaluate on seen and unseen projects	EAE-1	Evaluate and Analyze	Program Graphs for Code Analysis	Evaluation (#3)	Read the 'EAE-1 Evaluate on seen and unseen projects' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Evaluate and Analyze'). Follow its guidance when assisting me. Run evaluation on SEENPROJTEST (projects with files in training) and UNSEENPROJTEST (completely held-out projects). Report accuracy and PR-AUC for VARMISUSE; accuracy and F1 for VARNAMING. Expect lower performance on unseen projects due to unknown type lattices and different vocabularies.
Run ablation study	EAE-1	Evaluate and Analyze	Program Graphs for Code Analysis	Evaluation (#3)	Read the 'EAE-1 Run ablation study' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Evaluate and Analyze'). Follow its guidance when assisting me. Systematically vary: (1) edge types used — syntax only, semantic only, combined; (2) node label representation — subtokens vs full tokens vs disabled. Measure impact on both VARNAMING and VARMISUSE accuracy to attribute performance gains to specific design choices.
Compare against baselines	EAE-1	Evaluate and Analyze	Program Graphs for Code Analysis	Evaluation (#3)	Read the 'EAE-1 Compare against baselines' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Evaluate and Analyze'). Follow its guidance when assisting me. Compare GGNN against: LOC (local bidirectional GRU, no usage context), AVGBIRNN (bidirectional RNN averaged over all usages). For VARNAMING also compare against AVGLBL (log-bilinear model over 4-token context windows). All baselines use same variable selection objective: argmax of c(t)^T u(t,v).
Discover real-world bugs	EAE-1	Evaluate and Analyze	Program Graphs for Code Analysis	Evaluation (#3)	Read the 'EAE-1 Discover real-world bugs' activity from playbook 'Program Graphs for Code Analysis' (workflow 'Evaluate and Analyze'). Follow its guidance when assisting me. Rank variable usage locations by model confidence that a different variable should be used. Inspect the top-N locations (top 500 in the paper) where the model strongly disagrees with the ground truth. Classify findings as true bugs vs. valid alternatives (e.g. aliases). Report confirmed bugs with code snippets.