xcoder-dna 0.0.0-stage → 1.3.1

package/dist/skills/project-scaffolding/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: project-scaffolding
+role: scaffolding
+description: Turns an existing design document into a scaffolded, runnable repository — directory layout, package manifest, config, CI/dev-entry-point skeleton, and an initial git checkpoint — then hands off to implementation, one component at a time. Bridges software-architect/architect's design output and programmer/software-engineer's implementation work; neither of those covers the "zero to running skeleton" step.
+triggers:
+  - "scaffold"
+  - "scaffold the project"
+  - "scaffold a repository"
+  - "scaffold the repository"
+  - "bootstrap the project"
+  - "bootstrap a project"
+  - "project skeleton"
+  - "repo skeleton"
+  - "repository skeleton"
+  - "initialize the repository"
+  - "set up the repository"
+  - "greenfield project"
+  - "from the design document"
+  - "from the design doc"
+  - "implement the design document"
+  - "build from the design"
+version: "1.0.0"
+requires_tools:
+  - read_tool
+  - glob_tool
+  - grep_tool
+  - write_edit_tool
+  - run_command_tool
+  - github_tool
+composes_with:
+  - software-architect
+  - architect
+  - programmer
+  - software-engineer
+  - task-planning
+  - git-vcs
+  - devops
+  - workspace-context
+---
+
+## Process
+
+1. **Read the design document in full before creating anything.** `glob_tool` for the likely
+   names first if not given a path — `design.md`, `DESIGN.md`, `blueprint.md`,
+   `solution-design.md`, `docs/design/**/*.md`, `plan/*.md`. Extract, concretely: the chosen
+   tech stack (language/runtime/framework/versions if stated), the component/module list, the
+   external dependencies (databases, queues, third-party APIs), and any explicitly stated
+   directory-layout or naming conventions. If the design doc is silent on a structural
+   decision (e.g. monorepo vs. multi-package, test framework choice), pick the ecosystem's
+   own convention for the stated language rather than inventing one — don't ask the user for
+   things a design doc this detailed should already imply.
+2. **Compose with `task-planning` before writing files** if the component list has more than a
+   few items — turn the design into a WBS (one task per component/config artifact) so the run
+   gets scored on decisive, forward-moving steps instead of one undifferentiated "build
+   everything" action.
+3. **Scaffold structure and config first, implementation code second, in that order** — and
+   validate the skeleton actually installs/builds before writing a single line of feature code:
+   - Directory layout matching the design doc's module boundaries.
+   - Package manifest (`package.json`/`pyproject.toml`/`go.mod`/`Cargo.toml`/etc.) with the
+     dependencies the design doc names — not extras "just in case."
+   - `.gitignore` scoped to the actual stack (build output, dependency caches, local env
+     files) — not a generic copy-paste that ignores files the project actually needs tracked.
+   - A minimal entry point that runs/compiles with no real logic yet (e.g. a "hello world"
+     server route, an empty test that passes) — this is the checkpoint that proves the
+     scaffold itself works before any component logic is layered on.
+   - Run the install/build command (`run_command_tool`) and read the Observation. A scaffold
+     that "looks right" but was never actually installed/built is not validated — don't skip
+     this step even though it feels like overhead for boilerplate.
+4. **Commit the bare scaffold before implementing anything** (compose with `git-vcs`): `git
+   init` (if not already a repo) and one commit for the working skeleton. This is a direct
+   lesson from this project's own incident history (PM-2026-07-25-001's own P3 finding: "no git
+   history... impossible to trace when truncation first occurred or what changed") — a
+   scaffold with no checkpoint means any later mistake has no rollback point, and root-causing
+   it later has nothing to bisect against.
+5. **Implement component by component from the WBS, validating each one before moving to the
+   next** — write the code for one component, run its tests/linter/build (Validation phase),
+   then move on. Writing every component's code first and validating once at the end defeats
+   the point of incremental verification and produces a pile of unvalidated changes that are
+   hard to attribute a failure to.
+
+## Instructions — non-negotiable
+
+- **One file per `write_edit_tool` call, not one call dumping the whole scaffold.** Every file
+  this skill creates (manifest, config, source stub) should be its own `write_edit_tool` call
+  with `mode='write'`. This project's own `agent/config/llm.yaml` sizes `max_tokens` at 16384
+  (~57KB) specifically so that any single completion has a real ceiling — a single response
+  trying to emit an entire multi-file scaffold as one giant blob risks hitting
+  `finish_reason: "length"` mid-generation. `truncationGuard.ts` will now catch that and force a
+  clean retry instead of silently writing a truncated file (the actual root cause of
+  PM-2026-07-25-001), but relying on that safety net for routine scaffolding work is strictly
+  worse than just not generating oversized single completions in the first place.
+- **Check before you scaffold**: `glob_tool`/`grep_tool` for an existing manifest, `.git/`
+  directory, or non-empty target directory before treating this as greenfield. Scaffolding on
+  top of an existing project silently overwrites config — confirm the directory is actually
+  empty (or that overwriting specific named files is intended) before writing.
+- **Never invent a directory layout the design doc doesn't imply.** If the design doc specifies
+  module boundaries, the directory structure should map onto them directly — restructuring
+  "for cleanliness" beyond what's specified is scope creep on a scaffolding task and makes the
+  result harder to review against the doc it's supposed to implement.
+- **Config values that are secrets (API keys, DB credentials, tokens) go in a `.env.example`
+  with placeholder values and documentation, never a real `.env` with invented-looking real
+  values** — a scaffold's `.env.example` is a template, not a place to guess at credentials.
+
+## Strategies
+
+- Batch tightly-related, small config values into one file (e.g. `tsconfig.json`,
+  `.eslintrc`) rather than one `write_edit_tool` call per config key — the one-file-per-call
+  rule above is about avoiding oversized *individual* completions, not about maximizing the
+  number of tool calls for its own sake.
+- If the target ecosystem has a standard scaffolding tool (e.g. `npm create vite@latest`,
+  `cargo new`, `django-admin startproject`), prefer running it via `run_command_tool` over
+  hand-writing the same boilerplate it would generate — less surface area for a hand-written
+  config to drift from ecosystem convention, and it's a single verifiable command instead of
+  several hand-authored files that could each have a typo.
+- Prefer wiring cross-platform-safe entry points (a plain `npm start`/`make run`-style command
+  that works without assuming a specific shell) over OS-specific scripts as the *primary*
+  documented way to run the project, and only add OS-specific scripts (`.sh`/`.bat`) as
+  secondary conveniences layered on top — this project's own scripts hit real, confirmed bugs
+  from the opposite ordering (a heavy, POSIX-only script wired as the automatic entry point,
+  breaking on every platform including Linux due to a line-ending issue). Don't repeat that
+  shape in a new scaffold.
+
+## Experience
+
+- A design doc that names a tech stack but not exact versions is not license to pick whatever
+  is newest — check for a stated minimum/target version first (engines field, runtime version
+  file, CI config if the design doc references one); silently picking latest can introduce
+  compatibility problems the design doc's author didn't anticipate.
+- The most common scaffolding failure isn't a missing file, it's an unvalidated one — a
+  manifest that lists a dependency that doesn't actually resolve, or an entry point that was
+  never actually run. Always execute the install/build/run command and read its Observation
+  before considering the scaffold step done, exactly as `devops`'s "Validate" step requires for
+  a deploy pipeline — the same discipline applies here, just earlier in the lifecycle.

package/dist/skills/qa-engineer/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: qa-engineer
+role: qa
+description: Test strategy and quality verification — systematic coverage (boundary/edge cases, negative paths, regression) and structured bug reporting instead of only confirming the happy path works once.
+triggers:
+  - "test plan"
+  - "test strategy"
+  - "quality assurance"
+  - "write test cases"
+  - "regression test"
+  - "verify this works"
+  - "find bugs"
+  - "test coverage"
+  - "edge cases"
+version: "1.0.0"
+requires_tools:
+  - read_tool
+  - run_command_tool
+  - playwright_run_tool
+  - api_test_tool
+  - crawl_and_generate_playwright_test_tool
+composes_with:
+  - workspace-context
+  - task-planning
+  - software-engineer
+---
+
+<!-- xcoder:version 1 | xcoder:task task-ad2c3b | xcoder:updated 2026-11-04T15:34:54.851Z | xcoder:subtask code-st-8afddf -->
+
+## Precedence when a QA coverage run is active (read first)
+
+When the task carries `requirementsPath` — i.e. it is a QA coverage run (requirement → plan →
+Playwright → run → report) — this skill's coverage rule takes precedence over the happy-path
+heuristic in `playwright-ui-tester` ("the happy path plus the 1–2 realistic failure modes").
+
+The **requirement set**, not the happy-path heuristic, defines the scenario floor: every
+requirement admitted at intake needs at least one scenario, every scenario needs at least one
+Playwright test, and the test title must carry its `[REQ-nnn][SCN-...]` tags. Ad-hoc UI runs with
+no `requirementsPath` are unchanged and stay cheap.
+
+This precedence is guidance only. The plan-approval check, the title-tag check and the coverage
+gate are enforced in code (`src/qa-agent/qa-test-plan.ts`, `qa-spec-authoring.ts`,
+`coverage-gate.ts`) — a coverage number cannot be improved by anything written here.
+
+## Process
+
+1. Before writing test cases, identify the actual contract being tested: inputs, expected outputs,
+   documented error conditions, and any invariants that must always hold — read the code/spec
+   rather than guessing behavior from the function name.
+2. Cover the standard boundary set for every input: empty/null, zero, negative, maximum,
+   one-past-maximum, duplicate entries, and malformed/unexpected type — not just the example given
+   in the task. This is the single highest-value habit in this skill.
+3. Test negative/error paths explicitly: does the system fail the way it's supposed to (clear
+   error, correct status code, no data corruption), not just whether it succeeds on good input.
+4. For anything with concurrency or shared state, consider what happens when two operations race —
+   most real production bugs live here, not in single-threaded happy-path logic.
+5. When testing a UI, verify keyboard-only navigation and at least one non-desktop viewport in
+   addition to the primary click-through path — see the `ui-ux-design` skill for the specific
+   checklist when the target is a UI.
+6. After confirming a bug, write a minimal reproduction (smallest input/steps that still trigger
+   it) before reporting — a report with the smallest repro is fixed faster than one with the
+   original, more complex trigger.
+
+## Instructions — non-negotiable
+
+- Never report "it doesn't work" without the specific input, expected output, actual output, and
+  exact steps/command used — an unreproducible report has near-zero value.
+- Never mark a test as passing based on the absence of a crash alone — check the actual output/
+  return value against the expected one.
+- When automating tests (e.g. `playwright_run_tool`, `api_test_tool`), assert on specific expected
+  values/states, not just "the page loaded" or "the request returned 200" — a broken feature that
+  still returns 200 with wrong data will pass a weak assertion.
+- Flag flaky tests explicitly rather than silently re-running until green — a test that
+  intermittently fails is signal, not noise, and re-running to hide it defeats the point of testing.
+
+## Strategies
+
+- Prioritize testing effort by risk (what's most likely to break × how bad if it does), not by
+  what's easiest to test — a simple getter needs less attention than a payment calculation.
+- Prefer a small number of tests that exercise realistic user/system workflows end-to-end over a
+  large number of tests that only check trivial internals in isolation, when time is limited.
+- When a bug is found, ask whether the same class of input could break other similar code paths in
+  the codebase before considering the investigation complete.
+
+## Experience
+
+- The most common gap in AI-generated or rushed test suites is only testing the example from the
+  task description — deliberately test at least one input the task description never mentioned.
+- Bugs cluster at boundaries (off-by-one, empty collections, the first/last item in a loop, state
+  transitions) far more often than in the middle of straightforward logic — weight test design
+  accordingly.

package/dist/skills/rca/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: rca
+role: Root Cause Analysis
+description: >
+  Investigates incidents/bugs to find the actual root cause, not just the symptom. Load
+  whenever the task involves an incident, an unexplained failure, "why did this happen", or a
+  bug whose fix isn't obvious from the surface report.
+triggers: [rca, "root cause", incident, postmortem, "why did this fail", "why is this happening", outage]
+version: 1.0
+requires_tools: [read_tool, grep_tool, run_command_tool]
+composes_with: [tester, performance-tester, secops, programmer]
+---
+
+## Role
+Owns finding the actual causal chain behind a failure — not the first plausible explanation —
+and distinguishing root cause from contributing factors and symptoms.
+
+## Process
+1. **Establish the timeline** — what changed and when, correlated with when the symptom
+   started (deploys, config changes, traffic shifts, dependency updates).
+2. **Reproduce if possible** — a reproduced failure is far stronger evidence than log
+   inference alone.
+3. **Ask "why" iteratively** — keep pushing past the first answer until you reach something
+   actionable and structural, not just the proximate trigger.
+4. **Verify the hypothesis** — the true root cause should, when reverted/fixed, make the
+   symptom go away (Validation phase) and its absence should explain why the incident
+   wasn't happening before.
+5. **Separate root cause from contributing factors** — e.g., "no rate limit" (root) vs.
+   "traffic spike" (trigger) are different things; name both, fix the root.
+
+## Strategies
+- Prefer evidence (logs, metrics, repro) over plausible-sounding narrative.
+- Check "what changed recently" first — most incidents correlate with a recent change.
+- Consider multiple causal chains before committing to one; don't stop at the first fit.
+- Distinguish trigger (what set it off) from root cause (what made the system vulnerable to
+  that trigger).
+
+## Planning Approach
+- Timebox investigation phases: timeline reconstruction → hypothesis generation → hypothesis
+  verification, rather than open-ended digging.
+- Write the postmortem as you go (running notes), not reconstructed from memory afterward.
+
+## Instructions for This Task Type
+- Never present a hypothesis as the root cause without verification evidence.
+- Always produce a timeline and explicitly list contributing factors alongside the root
+  cause, plus a corrective action for each.
+
+## Experience / Common Pitfalls
+- Stopping at the proximate cause ("the server crashed") instead of the structural cause
+  ("no memory limit + unbounded cache growth") leads to recurrence.
+- Blame-oriented framing ("who broke this") derails RCA from its purpose — focus on system
+  and process gaps.
+
+## Output Artifacts
+- Timeline
+- Root cause + contributing factors
+- Corrective actions (with owners/priority if known)
+- Postmortem doc

package/dist/skills/redhat/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: redhat
+role: devops
+description: Administer RHEL/CentOS/Rocky/Alma servers — dnf/yum package management, subscription-manager registration, SELinux troubleshooting, and firewalld — the RHEL-family equivalents that differ meaningfully from Debian/Ubuntu conventions.
+triggers:
+  - "red hat"
+  - "redhat"
+  - "rhel"
+  - "centos"
+  - "rocky linux"
+  - "dnf install"
+  - "yum install"
+  - "selinux"
+  - "firewalld"
+  - "subscription-manager"
+version: "1.0.0"
+requires_tools:
+  - run_command_tool
+  - ssh_tool
+  - ssh_copy_tool
+composes_with:
+  - workspace-context
+  - openshift
+  - rosa
+  - docker
+---
+
+## Process
+
+1. On RHEL proper (not CentOS Stream/Rocky/Alma), register the system with
+   `subscription-manager register` and attach an appropriate subscription/enable the needed repos
+   before `dnf install` — unregistered RHEL has no package repos enabled by default, unlike
+   Ubuntu's apt which works out of the box. This is the most common "package not found" surprise
+   for anyone coming from Debian-family systems.
+2. Use `dnf` (RHEL 8+/CentOS Stream/Rocky/Alma) or `yum` (RHEL 7 and older) — `dnf` is the modern
+   tool and is what current guidance should target; confirm the actual OS version rather than
+   assuming.
+3. Check SELinux status (`getenforce`) before debugging a "permission denied" that looks otherwise
+   inexplicable — SELinux enforces mandatory access control independent of standard Unix
+   permissions, and a process can have correct file permissions and still be blocked by policy.
+4. Manage the firewall with `firewall-cmd` (firewalld), not raw `iptables`, on modern RHEL-family
+   systems — firewalld is the standard front-end and mixing direct iptables rules with it causes
+   confusing, hard-to-reproduce state.
+5. Use systemd (same as Ubuntu) for service management — this part is consistent across the
+   Linux distributions covered here, unlike package management and MAC (mandatory access control).
+
+## Instructions — non-negotiable
+
+- Never resolve a SELinux-caused denial by running `setenforce 0` (disabling enforcement) on a
+  production/shared system — diagnose the specific denial (see sequence below) and fix the context
+  or write a targeted policy exception instead. Disabling SELinux removes a real security layer
+  system-wide for the sake of one local issue.
+- Never open a firewalld port with `--zone=public` when a more restrictive zone would do — scope
+  to the minimum needed.
+- Always make firewalld changes with `--permanent` and then `firewall-cmd --reload` — without
+  `--permanent`, changes vanish on the next reboot, which reliably confuses anyone testing a change
+  and forgetting to persist it.
+- Never assume CentOS Stream/Rocky/Alma package availability is identical to RHEL — they track
+  RHEL closely but aren't guaranteed bit-identical; verify a package/repo exists for the specific
+  distro and version in use.
+
+## Strategies
+
+- Prefer `dnf module` for software with multiple available versions (e.g. different language
+  runtime streams) over manually adding third-party repos, when a module stream provides what's
+  needed — keeps the system on RHEL's supported package paths.
+- When SELinux blocks something legitimate repeatedly, prefer a scoped `semanage`/policy module fix
+  for the specific context over broad `setenforce 0`/`chcon` one-offs that don't survive a
+  relabel and don't document why the exception exists.
+- For services listening on non-standard ports, remember SELinux also tracks expected port-to-service
+  type mappings (`semanage port -l`) independent of the firewall — a firewalld rule alone isn't
+  always sufficient if SELinux's port type doesn't match.
+
+## Diagnostic sequence for SELinux-blocked access
+
+1. `getenforce` — confirm SELinux is actually in `Enforcing` mode (vs. `Permissive`/`Disabled`)
+   before spending time chasing an SELinux theory for a non-SELinux problem.
+2. `ausearch -m avc -ts recent` (or `grep AVC /var/log/audit/audit.log`) — find the actual denial
+   and what it was trying to do.
+3. `sealert -a /var/log/audit/audit.log` (if `setroubleshoot` is installed) — gives a human-readable
+   explanation and the specific suggested fix command, usually a `semanage`/`setsebool` invocation.
+4. Apply the narrowest suggested fix (a specific boolean or file context change) rather than the
+   broadest one offered.
+
+## Experience
+
+- "It works when I run it manually as root but not as the service" combined with correct file
+  permissions is the classic SELinux signature — check `getenforce` and AVC denials before
+  anything else once permissions are confirmed correct.
+- A firewalld rule that "isn't working" after being added is very often the missing `--permanent`
+  + `--reload`, or being added to the wrong zone (`firewall-cmd --get-active-zones` shows which
+  zone the actual interface is using) rather than a genuinely wrong rule.

package/dist/skills/rosa/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: rosa
+role: devops
+description: Provision and operate Red Hat OpenShift Service on AWS (ROSA) — the AWS-account and STS prerequisites specific to managed OpenShift, how much is Red-Hat-managed vs. customer-managed, and the cluster-creation/upgrade workflow via the rosa CLI.
+triggers:
+  - "rosa cluster"
+  - "red hat openshift service on aws"
+  - "openshift on aws"
+  - "provision rosa"
+  - "rosa cli"
+version: "1.0.0"
+requires_tools:
+  - run_command_tool
+  - ssh_tool
+  - read_tool
+composes_with:
+  - workspace-context
+  - openshift
+  - aws
+  - kubernetes
+---
+
+## Process
+
+1. Understand the managed-service boundary before doing anything else: Red Hat and AWS jointly
+   operate and are responsible for the control plane (masters, etcd, the OpenShift platform itself,
+   patching, SLA); the customer is responsible for what runs on worker nodes (applications, their
+   configuration and security) and for the AWS account/IAM setup the cluster lives inside. Don't
+   plan control-plane-level changes (etcd tuning, master node access) that ROSA doesn't expose —
+   that's intentionally not customer-managed.
+2. Set up prerequisites in order: an AWS account meeting ROSA's requirements, the `rosa` CLI and
+   `oc` CLI installed, `rosa login`, then `rosa create account-roles` and (for STS clusters, the
+   modern default) `rosa create operator-roles`/`oidc-provider` before `rosa create cluster`.
+   Skipping the account-roles/operator-roles step is the most common cause of cluster creation
+   failing partway through.
+3. Prefer STS (Security Token Service) mode over the older non-STS/IAM-credentials mode for new
+   clusters — narrower, per-operator IAM permissions instead of one broad set of long-lived
+   credentials; this is the current recommended default.
+4. Plan networking (VPC CIDR, subnet layout across AZs, whether it's a public or fully-private
+   cluster) before creation — networking topology is far more disruptive to change after cluster
+   creation than most other settings.
+5. Once created, treat it as OpenShift for day-to-day operations (see the `openshift` skill for
+   `oc`, projects, routes, S2I) — ROSA is standard OpenShift underneath; the ROSA-specific concerns
+   are almost entirely at the provisioning/AWS-integration layer, not day-to-day workload management.
+
+## Instructions — non-negotiable
+
+- Never attempt to modify control-plane/master node configuration directly — it's not exposed for
+  customer modification and isn't the supported path even where technically reachable; use
+  cluster-level OpenShift configuration objects (`Machine­Config`, operators) for anything that
+  needs to be customer-configured.
+- Never share the AWS IAM credentials used for cluster creation broadly — scope `rosa` CLI access
+  to the specific people/automation that need to manage cluster lifecycle, following the same
+  least-privilege principle as any other AWS IAM usage.
+- Confirm the target AWS region actually supports ROSA before planning around it — availability is
+  not universal across all AWS regions.
+- Plan and budget for both AWS infrastructure costs (EC2, EBS, load balancers, data transfer) and
+  the separate ROSA service fee — these are billed differently and both need to be accounted for.
+
+## Strategies
+
+- Use multi-AZ cluster topology for production; single-AZ is a reasonable cost tradeoff for
+  dev/test only.
+- Prefer cluster autoscaling (`rosa create autoscaler`/machine pool min/max) over statically sized
+  worker node counts for variable workloads, to avoid both over-provisioning cost and
+  under-provisioning capacity crunches.
+- For multi-cluster setups (e.g. separate clusters per environment), keep the account-roles/
+  operator-roles naming consistent and documented — becomes hard to track which IAM roles serve
+  which cluster otherwise.
+
+## Experience
+
+- Cluster creation failures most often trace back to an incomplete or out-of-order prerequisite
+  step (missing account-roles, expired/insufficient IAM permissions on the creating principal, or
+  a service quota limit in the target AWS account/region) rather than a `rosa create cluster`
+  parameter being wrong — check `rosa describe cluster -c <name>` and `rosa logs install -c <name>`
+  for the actual failure stage before re-attempting.
+- Upgrades are cluster-scoped and versioned like standard OpenShift — check `rosa list upgrade -c
+  <name>` for available versions and known upgrade-path constraints before scheduling one, same
+  discipline as any other production OpenShift upgrade.

package/dist/skills/scrum-framework/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: scrum-framework
+role: Scrum Coach / Framework Reference
+description: >
+  Reference and coaching knowledge for Scrum — the four roles (Product Owner, Scrum Master,
+  Developers, Architect), the five events (Sprint Planning, Daily Scrum, Backlog Refinement,
+  Sprint Review, Retrospective), the three artifacts and commitments (Product Backlog/Product
+  Goal, Sprint Backlog/Sprint Goal, Increment/Definition of Done), sprint rules, INVEST story
+  quality, and Definition of Ready/Done. Load whenever the task involves explaining or coaching
+  Scrum roles and accountabilities, running or facilitating a Scrum event, writing or critiquing
+  a Sprint Goal or user story, checking a story against INVEST or Definition of Ready/Done,
+  evaluating "is this good Scrum" or spotting anti-patterns, or drafting product backlog items,
+  acceptance criteria, or facilitation agendas.
+triggers: [scrum, sprint, "product backlog", "sprint goal", "user story", "acceptance criteria", invest, "definition of done", "definition of ready", retrospective, "daily scrum", "sprint planning", "sprint review", "product owner", "scrum master"]
+version: 1.0
+requires_tools: []
+composes_with: [scrum-master-agent]
+---
+
+
+# Scrum Framework
+
+Reference knowledge for coaching, explaining, and applying Scrum correctly. Ground every answer in accountability: each role owns exactly one thing and cannot delegate it, each artifact carries exactly one commitment, and every event is a timeboxed inspect-and-adapt opportunity, not a status meeting.
+
+## When to go deeper
+
+- Full role responsibilities, sprint cycle, and event-by-event agendas: `references/roles_and_events.md`
+- Artifacts, commitments, DoR/DoD, INVEST, and Scrum anti-patterns: `references/artifacts_and_quality.md`
+
+Read the relevant reference file before writing detailed coaching content (e.g. a full Sprint Planning agenda, a DoD checklist, or an INVEST review) — don't reconstruct these from memory alone, since the specifics (timeboxes, question sets, checklist items) matter.
+
+## Core mental model
+
+**Four roles, one accountability each** (Architect is not a canonical Scrum Guide role but is commonly added in technical/CBD-style teams):
+- **Product Owner** — accountable for the *value* of the product. Owns the Product Backlog: content, ordering, clarity. Says what and why, never how.
+- **Scrum Master** — accountable for the *effectiveness of the Scrum Team*. Servant-leader: facilitates events, removes impediments, coaches — not a project manager and has no authority over the backlog or the team's work.
+- **Developers** — accountable for a *usable Increment* every Sprint. Self-organizing, cross-functional, own the Sprint Backlog and estimation collectively.
+- **Architect** (non-canonical, common in technical orgs) — owns the technical blueprint/design decisions and architectural review; not a source of process authority.
+
+No one holds more than one primary accountability, and accountabilities are non-transferable — don't recommend workarounds that blur them (e.g. a Scrum Master accepting stories, or a PO estimating).
+
+**Five events, each with a hard timebox (a maximum, not a target):**
+1. Sprint Planning (≤8 hrs/4-wk sprint) — produces the Sprint Goal + Sprint Backlog
+2. Daily Scrum (15 min, daily) — inspects progress, replans next 24h; not a status report
+3. Backlog Refinement (≤10% of sprint capacity, continuous, not a formal timeboxed event) — gets items to "Ready"
+4. Sprint Review (≤4 hrs/4-wk sprint) — demonstrates the *working* Increment, gathers stakeholder feedback
+5. Sprint Retrospective (≤3 hrs/4-wk sprint) — produces 1–3 specific, owned improvement actions for the next sprint
+
+**Three artifacts, three commitments:**
+| Artifact | Owner | Commitment |
+|---|---|---|
+| Product Backlog | Product Owner | Product Goal |
+| Sprint Backlog | Developers | Sprint Goal |
+| Increment | Developers | Definition of Done |
+
+## Non-negotiable sprint rules
+
+- Only the PO can cancel a Sprint, and only if the Sprint Goal becomes obsolete — this is rare.
+- No scope changes that endanger the Sprint Goal mid-sprint.
+- Sprint length is fixed; never extend to finish late work.
+- Unfinished stories return openly to the Product Backlog — never silently carried over.
+- If an item doesn't meet the Definition of Done, it is not Done. No partial credit.
+
+## Writing a good Sprint Goal
+
+A Sprint Goal answers "why are we doing this Sprint?" and gives Developers flexibility in *what exactly* they build to get there.
+- Good: "Enable customers to check out via Stripe so we can launch payments to beta users."
+- Bad: "Complete stories SP-142, SP-144, SP-145, SP-147." (a task list, not a goal — gives no room to adapt)
+
+## Quick answers vs. deep answers
+
+For a simple factual question ("what's the Daily Scrum timebox?", "who owns the Sprint Backlog?") answer directly and briefly from the core mental model above — no need to open the reference files.
+
+For anything requiring a full checklist, agenda, or scored evaluation (drafting a Sprint Planning agenda, checking a story against DoR/DoD, scoring INVEST, listing anti-patterns), open the relevant reference file first so specifics are accurate rather than reconstructed from memory.

package/dist/skills/scrum-framework/references/artifacts_and_quality.md

@@ -0,0 +1,79 @@
+# Artifacts, Quality Gates, and Anti-Patterns
+
+## The three artifacts
+
+### Product Backlog — owned by the Product Owner, commitment: Product Goal
+The single, ordered list of everything known to be needed in the product. Dynamic — always exists as long as the product does, never "complete." The PO alone is responsible for its content, availability, and ordering.
+
+A good Product Backlog Item (PBI) contains:
+- User Story (As a / I want / So that)
+- Acceptance Criteria (Given/When/Then)
+- Story Points estimate
+- Priority / business value
+- Epic linkage (if applicable)
+- Definition of Ready status
+
+### Sprint Backlog — owned by the Developers, commitment: Sprint Goal
+The Sprint Goal, the PBIs selected for the Sprint, and an actionable delivery plan. A highly visible, real-time snapshot of the Developers' plan. Only Developers modify it during the Sprint.
+
+Components: Sprint Goal (the "why") · Selected PBIs (the "what") · Task breakdown ≤1 day each (the "how") · daily updates reflecting actual remaining work · burndown showing progress to goal.
+
+### Increment — owned by the Developers, commitment: Definition of Done
+A concrete, usable stepping stone toward the Product Goal. Additive to all prior Increments, verified working. Multiple Increments may be created within a single Sprint. Delivered at Sprint Review, not merely demoed.
+
+Quality gates for an Increment:
+- Meets Definition of Done without exception
+- All acceptance criteria verified by the PO
+- Integrates cleanly with previous Increments
+- Deployable to production at any time
+- No known defects above the agreed threshold
+
+## Definition of Ready (DoR) — gate before Sprint Planning
+A story is Ready when it has: Title · Description · Acceptance Criteria · Estimate · No open questions. Stories that skip this gate derail Sprint Planning.
+
+## Definition of Done (DoD) — gate before a story counts as Done
+A formal, team-agreed quality bar. If an item doesn't meet it, it is not Done — no exceptions and no partial credit. A representative DoD:
+- Code reviewed and approved
+- Unit tests written and passing (commonly ≥80% coverage)
+- Integration tests passing
+- No new linting or type errors
+- Deployed to staging environment
+- Acceptance criteria verified by the PO
+
+When reviewing a real story against DoD, list the specific unmet items rather than a pass/fail verdict — e.g. "missing: integration tests, staging deploy" is actionable; "not Done" is not.
+
+## The Three Commitments
+
+- **Product Goal** — commits the team to a long-term vision (backs the Product Backlog).
+- **Sprint Goal** — commits the team to what they'll achieve this Sprint (backs the Sprint Backlog).
+- **Definition of Done** — commits the team to the quality standard applied to every Increment.
+
+These give the artifacts context and prevent misinterpretation — Scrum's transparency only works if all three are explicit and shared.
+
+## INVEST — evaluating story quality
+
+Score each criterion individually rather than giving one aggregate pass/fail; name the specific gap.
+
+- **Independent** — can be built and delivered without hard dependency on another unscheduled story
+- **Negotiable** — describes outcome, not a rigid spec; room for the how to be worked out
+- **Valuable** — delivers value to a user or the business, not just a technical task
+- **Estimable** — the team has enough clarity to size it
+- **Small** — fits comfortably within a single Sprint (common flag: >13 points signals a split is needed)
+- **Testable** — has clear, verifiable acceptance criteria (Given/When/Then is the standard structure)
+
+When a story fails a criterion, suggest a concrete rewrite rather than just naming the failure — e.g. for a missing Testable criterion: draft the Given/When/Then acceptance criteria yourself as a starting point.
+
+## Common Scrum anti-patterns to watch for and name
+
+- **Zombie sprints** — sprints that continue in form (events happen) but have lost real inspect-and-adapt substance; teams go through the motions without changing behavior based on what they learn.
+- **Sprint padding** — inflating estimates or scope to guarantee an easy "success," which erodes the value of velocity as a planning signal.
+- **Cargo-cult Scrum** — following the mechanics (standups, sprints, boards) without understanding or honoring the underlying purpose (transparency, inspection, adaptation).
+- **Silent carryover** — unfinished work rolling to the next sprint without being explicitly returned to and re-prioritized in the Product Backlog.
+- **Status-report Daily Scrum** — reporting to a manager instead of replanning as a team.
+- **PO absentee** — Developers making value/priority calls the PO should own, or accepting their own work.
+- **Scope creep endangering the Sprint Goal** — adding work mid-sprint without evaluating impact on the committed goal.
+- **Task-list Sprint Goals** — a Sprint Goal that's just an enumerated list of ticket IDs, giving no flexibility or "why."
+
+## Scaled Scrum (brief context only)
+
+For organizations running multiple Scrum teams on one product, common scaling frameworks include **Nexus**, **LeSS** (Large-Scale Scrum), and **SAFe** (Scaled Agile Framework). These add cross-team coordination events and roles on top of — not instead of — the core Scrum framework above. Give only a brief pointer unless the user specifically wants scaling guidance; the core framework applies at the single-team level regardless.