spectoflow 0.12.0

package/templates/skills/write-adr/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: write-adr
+description: Record an architecturally significant decision as a short, durable ADR.
+capability: architecture
+inputs: The design under discussion (components/boundaries, framed by C4 views) and the options weighed.
+outputs: An ADR file recording context, decision, and consequences.
+standard: "ADR (Nygard/MADR) + C4"
+---
+# Write ADR
+
+Capture one architecturally significant decision — the forces behind it, what was chosen, and what it
+costs — so the reasoning survives past the conversation that produced it.
+
+## When to use
+Whenever a decision has lasting consequence: it constrains a boundary, an interface, a technology
+choice, or a trade-off that would be expensive to reverse. Not for routine implementation choices a
+developer can freely change later.
+
+## Method
+Frame the decision against the relevant C4 view first — is this a System Context decision (an external
+dependency or actor), a Container decision (a new service, store, or protocol between them), or a
+Component decision (internal structure of one container)? Naming the level keeps the ADR scoped to one
+decision instead of drifting into a general design doc. Then record it using Nygard's four-part
+structure (default) or MADR's fuller field set when the trade-off between options needs to be visible:
+
+1. **Title.** A short noun phrase naming the decision, numbered — `NNNN-title.md`.
+2. **Status.** `proposed`, `accepted`, `deprecated`, or `superseded by NNNN`.
+3. **Context.** The forces and constraints in play, stated as fact, not argument for the decision.
+   (MADR: also list **Decision drivers** explicitly if more than one competing force is at play.)
+4. **Decision.** What was decided, in full sentences, active voice: "We will …".
+   (MADR: list the **Considered options**, and for each, brief pros/cons, before naming the outcome —
+   this is what makes a later "why not X" answerable without re-litigating.)
+5. **Consequences.** What becomes easier or harder as a result — positive, negative, and neutral. Name
+   what was rejected and why, not just what was chosen.
+
+## Output contract
+Write one file per decision to the project's ADR location — `docs/adr/NNNN-title.md` if the project has
+no other convention, else the location the project already uses (check for an existing `docs/adr/` or
+`specs/adr/` directory before creating a new one). Use granular writes (one section at a time). Report
+via the `::spectoflow` sentinel:
+
+```
+::spectoflow role=architecture kind=progress msg=ADR drafted: docs/adr/NNNN-title.md
+::spectoflow role=architecture kind=report msg=ADR accepted: NNNN-title (<N> options considered)
+```
+
+A decision that supersedes an earlier ADR updates that ADR's Status line (`superseded by NNNN`) and is
+reported as its own event, never a silent edit.
+
+## Quality bar
+- [ ] Framed at the right C4 level — the ADR states which boundary/container/component it constrains.
+- [ ] Context is stated as fact (forces/constraints), not as an argument for the chosen option.
+- [ ] Considered options are named with their trade-offs, not only the winner.
+- [ ] Consequences cover positive, negative, and neutral — not just the upside.
+- [ ] Status is current; a reversed or replaced decision points to its successor, it isn't deleted.
+
+## References
+- Michael Nygard, "Documenting Architecture Decisions" (2011), the original ADR format —
+  https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
+- MADR (Markdown Any Decision Records) template — https://adr.github.io/madr/
+- Simon Brown, "The C4 model for visualising software architecture" — https://c4model.com/

package/templates/skills/write-e2e-tests/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: write-e2e-tests
+description: Author durable, CI-runnable end-to-end tests with Playwright — locators over selectors, web-first assertions, no hard waits.
+capability: testing
+inputs: The user-visible flow(s) under test (spec acceptance criteria or a plan task), the running app under test, and its existing `tests/e2e/` suite and Playwright config if any.
+outputs: Committed Playwright spec files under `tests/e2e/*.spec.ts`, runnable in CI.
+standard: Playwright
+---
+# Write end-to-end tests
+
+Author a durable, CI-runnable Playwright suite that exercises real user-visible flows — the committed
+artifact the project can re-run forever, distinct from one-off live/exploratory checks.
+
+## When to use
+When the workflow reaches an Integration or End-to-end tests step for a flow that spans multiple pages,
+services, or a full user journey, and the result needs to live in the repo and run again in CI on every
+change — not just be eyeballed once.
+
+## Method
+Practices below are current Playwright guidance (see References for exact source pages).
+1. **Test user-visible behavior, not implementation.** Assert on what an end user actually sees and does
+   — text, roles, visible state — never internal state or private methods. This keeps tests resilient
+   to refactors.
+2. **Locate elements the way a user would find them.** Prefer `page.getByRole()`, `getByText()`,
+   `getByLabel()`, `getByTestId()` over CSS/XPath selectors — user-facing locators survive DOM churn that
+   breaks structural selectors. Reserve `getByTestId()` for elements with no meaningful role/text.
+3. **Use web-first assertions, never manual polling.** Write `await expect(locator).toBeVisible()`,
+   `.toHaveText(...)`, etc. — these auto-retry until the condition holds or the timeout expires. Never
+   use `page.waitForTimeout()` in a committed test: it is a fixed sleep, is explicitly documented as
+   debug-only, and is the single biggest source of flakiness. If a wait is genuinely needed, wait for a
+   specific state/locator/response, never a clock duration.
+4. **Lean on built-in test isolation.** Each `test()` gets a fresh `page` / `BrowserContext` for free —
+   do not share mutable state between tests. For data that must be unique per run, use worker-scoped
+   fixtures (e.g. keyed by `test.info().workerIndex`) rather than global setup that couples tests
+   together.
+5. **Extend fixtures instead of repeating setup.** When multiple specs need the same login, seeded data,
+   or page object, define it once via `test.extend()` and consume it as a fixture parameter — do not
+   copy-paste setup code across spec files.
+6. **Configure `projects` for the matrix you actually need** (browsers, smoke vs. full suite, retries per
+   project) in the project's `playwright.config.ts` — this skill authors specs against that config, and
+   proposes config changes only when a task requires a new project/browser target.
+7. **Turn on `trace: 'on-first-retry'`** (with `retries` set for CI) so a flaky/failing run leaves a
+   debuggable trace without paying the cost of tracing every green run.
+8. **Keep specs scoped to one flow each**, named for the behavior under test, and placed under
+   `tests/e2e/*.spec.ts` in the user's project.
+
+**Live/exploratory verification is not this skill's output.** When an agent needs to *see* a change work
+right now (e.g. eyeballing a UI during development), it uses its native browser tooling (for Claude Code,
+the Chrome extension / `claude-in-chrome`) to drive the real browser interactively. If that tooling is
+unavailable, the fallback is Playwright in headed mode or `playwright codegen` for a quick, throwaway
+look — never a substitute for the committed suite. Either way, the durable, CI-runnable artifact this
+skill produces is always the Playwright spec file, not the live session.
+
+**Playwright is a dependency of the user's project, never of spectoflow.** This skill authors tests
+against whatever Playwright version the target project has (or proposes adding `@playwright/test` as a
+project devDependency when none exists) — spectoflow itself stays at zero runtime dependencies per
+`CLAUDE.md`.
+
+## Output contract
+- One or more `tests/e2e/*.spec.ts` files committed to the user's project, each runnable via the
+  project's Playwright config (`npx playwright test`) in CI with no manual step.
+- No `waitForTimeout` / fixed sleeps; assertions are web-first (`expect(locator)...`); locators are
+  role/text/label/testid based, not brittle CSS/XPath.
+- Progress and completion reported to the orchestrator and group chat with:
+
+```
+::spectoflow role=testing kind=progress msg=<flow name> — spec drafted
+::spectoflow role=testing kind=result msg=<spec file> <pass|fail> (<n> tests)
+::spectoflow role=testing kind=done msg=<flow name> e2e suite committed at tests/e2e/<file>
+```
+
+## Quality bar
+- [ ] Each spec asserts user-visible behavior (text/role/state), not internal implementation.
+- [ ] Locators use `getByRole`/`getByText`/`getByLabel`/`getByTestId`, not CSS/XPath selectors.
+- [ ] All assertions are web-first (`await expect(...)`); zero `waitForTimeout` calls in committed specs.
+- [ ] Tests are isolated — no shared mutable state between tests; per-worker data via fixtures where
+      parallel runs need unique data.
+- [ ] Repeated setup (login, seed data, page objects) lives in a shared fixture, not copy-pasted.
+- [ ] Suite is committed under `tests/e2e/` and runs headless in CI via the project's Playwright config.
+- [ ] `trace: 'on-first-retry'` (or equivalent) is set so a CI failure is debuggable without tracing
+      every run.
+- [ ] No spectoflow file declares Playwright as a dependency — only the user project's `package.json`.
+
+## References
+- Playwright — Best Practices — https://playwright.dev/docs/best-practices (test user-visible behavior;
+  prefer user-facing locators over XPath/CSS; use web-first assertions).
+- Playwright — Locators — https://playwright.dev/docs/locators (`getByRole`, `getByText`, `getByLabel`,
+  `getByTestId`).
+- Playwright — Auto-waiting / web-first assertions — https://playwright.dev/docs/actionability and
+  https://playwright.dev/docs/api/class-frame (`waitForTimeout` documented as debug-only; never use in
+  production tests).
+- Playwright — Test fixtures — https://playwright.dev/docs/test-fixtures (`test.extend()`, worker-scoped
+  fixtures for per-worker isolation).
+- Playwright — Test isolation — https://playwright.dev/docs/writing-tests (each test gets its own
+  `page`/`BrowserContext`).
+- Playwright — Projects — https://playwright.dev/docs/test-projects (per-project browser/retry/file
+  matching configuration).
+- Playwright — Trace viewer — https://playwright.dev/docs/trace-viewer (`trace: 'on-first-retry'` for
+  CI).

package/templates/skills/write-plan/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: write-plan
+description: Break an approved, designed spec into small, dependency-ordered, checkbox tasks.
+capability: planning
+inputs: A signed-off spec (specs/<feature>.md) and its architecture/ADRs, if any.
+outputs: plans/<feature>.md — dependency-ordered checkbox tasks.
+standard: INVEST
+---
+# Write plan
+
+Decompose an approved spec into tasks small and independent enough to execute one at a time, ordered so
+nothing starts before what it depends on exists.
+
+## When to use
+Once a spec is signed off (and, when the change is architecturally significant, once the architect has
+defined boundaries/ADRs), or whenever the workflow reaches the Plan step.
+
+## Method
+1. **Slice to INVEST size.** Break the spec's requirements into tasks that are each Independent,
+   Negotiable, Valuable, Estimable, Small, and Testable (Bill Wake). A task that can't be estimated or
+   tested on its own is still too big — split it again before it goes in the plan.
+2. **Order by dependency.** Group into phases (`##` headings) and sequence tasks so every dependency
+   appears before what needs it — data/schema before the services that read it, services before the UI
+   that calls them, cross-cutting infra before the features built on it. State a cross-task dependency
+   explicitly in the task line or a short note, never leave it implicit.
+3. **Write each task as a checkbox line** using the repo's task convention exactly:
+   `- [ ] T-012 Title @owner ~level %status`
+   - `T-012` — a stable, sequential task ID (never reused, never renumbered after creation).
+   - `Title` — outcome-phrased, short enough to scan.
+   - `@owner` — who/what role picks it up (`@dev`, `@qa`, agent name, or a person).
+   - `~level` — size signal, one of `~quick` / `~standard` / `~major` — keep it Small by this skill's
+     standard; a task that only fits `~major` is a candidate to split further.
+   - `%status` — current status, one of `%in_progress` / `%to_validate` / `%to_analyze` / `%blocked`.
+     A task not yet started carries **no** `%status` tag at all (todo = absent, not `%todo`). A finished
+     task is marked by checking the box (`- [x]`), never by a `%done` tag.
+4. **Check INVEST before closing the plan.** Re-scan the list: any task not independent, not small, or
+   not testable gets split or re-scoped before the plan is handed off.
+
+## Output contract
+Write `plans/<feature>.md` with phase headings (`##`) grouping dependency-ordered checkbox tasks in the
+exact line format above. Use granular writes (one task/line at a time, not one giant dump — the
+dashboard tracks each line). Report via the `::spectoflow` sentinel:
+
+```
+::spectoflow role=planning kind=progress msg=plan drafted: plans/<feature>.md (<N> tasks)
+::spectoflow role=planning kind=report msg=plan ready: <feature> (<N> tasks, <M> phases)
+```
+
+A plan revised after a task reveals a missing dependency is reported again, not silently edited.
+
+## Quality bar
+- [ ] Every task line matches `- [ ] T-xxx Title @owner ~level %status` exactly, with `~level` from
+      `{quick, standard, major}` and `%status` from `{in_progress, to_validate, to_analyze, blocked}` —
+      never invented tags.
+- [ ] A not-yet-started task carries no `%status` tag (todo = absent); a finished task is `- [x] …` with
+      no `%status` tag, never `%done`.
+- [ ] Every task is Independent, Small, and Testable enough to be picked up and closed on its own
+      (INVEST); nothing in the plan is a disguised multi-task epic.
+- [ ] Tasks are grouped into phases and ordered so no task precedes a dependency it needs.
+- [ ] Task IDs are stable and sequential; none are reused or skipped without reason.
+- [ ] The plan traces back to the spec's requirements — no task exists that isn't grounded in one.
+
+## References
+- Bill Wake, "INVEST in Good Stories, and SMART Tasks" (2003) —
+  https://xp123.com/invest-in-good-stories-and-smart-tasks/
+- Agile Alliance, "What does INVEST Stand For?" — https://agilealliance.org/glossary/invest/

package/templates/skills/write-spec/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: write-spec
+description: Produce a clear, reviewable specification in markdown, signed off before design/code starts.
+capability: analysis
+inputs: Acceptance criteria and edge cases from analyze-requirements, plus any known constraints.
+outputs: specs/<feature>.md — a reviewable, signed-off spec.
+standard: spec-kit / OpenSpec conventions
+---
+# Write spec
+
+Shape acceptance criteria into a single reviewable spec document, then drive it to explicit sign-off.
+
+## When to use
+Once `analyze-requirements` has produced acceptance criteria and edge cases for a feature or change, or
+whenever the workflow reaches the Spec step.
+
+## Method
+Structure the document like GitHub `spec-kit`'s spec template and OpenSpec's requirement/scenario
+format — behavior contract, not implementation plan:
+
+1. **Purpose.** 1-2 sentences: what this capability provides and to whom. No design detail.
+2. **Requirements.** Numbered (`REQ-001`, `REQ-002`, …), each phrased with RFC 2119 strength —
+   **MUST** (mandatory), **SHOULD** (recommended, exceptions allowed), **MAY** (optional). One
+   requirement = one testable statement, not a paragraph of intent.
+3. **Scenarios.** Under each requirement, one or more concrete scenarios in Given/When/Then, sourced
+   directly from `analyze-requirements`' criteria and edge cases (happy path + boundaries + error
+   paths). Mark any unresolved detail inline as `[NEEDS CLARIFICATION: …]` rather than guessing.
+4. **Out-of-scope.** What this spec deliberately does not cover — prevents silent scope creep during
+   implementation.
+5. **Open questions.** Anything still unresolved, each tagged as a `need` per `policy.md` if it blocks
+   a decision this role can't make alone.
+6. **Review loop.** Show the draft to the requester/stakeholders. Revise on feedback. The spec is only
+   "done" once it has explicit sign-off recorded — never inferred from silence.
+
+## Output contract
+Write `specs/<feature>.md` with exactly these sections, in order: Purpose, Requirements, Scenarios,
+Out-of-scope, Open questions. Use granular writes (one line/section at a time, not one giant dump).
+Report via the `::spectoflow` sentinel:
+
+```
+::spectoflow role=analysis kind=progress msg=spec draft written: specs/<feature>.md
+::spectoflow role=analysis kind=review msg=spec sent for sign-off: <feature>
+::spectoflow role=analysis kind=report msg=spec signed off: <feature> (<N> requirements, <M> scenarios)
+```
+
+A spec revised after feedback is reported again, not silently overwritten.
+
+## Quality bar
+- [ ] All five sections present, in order: Purpose, Requirements, Scenarios, Out-of-scope, Open
+      questions.
+- [ ] Every requirement uses MUST/SHOULD/MAY and is independently testable.
+- [ ] Every requirement has at least one Given/When/Then scenario grounded in real acceptance criteria
+      (not invented after the fact).
+- [ ] No implementation detail (class names, frameworks, data schemas) leaks into Requirements or
+      Scenarios.
+- [ ] Explicit sign-off is recorded before the spec is treated as done; unresolved items are tagged
+      `[NEEDS CLARIFICATION: …]` or raised as a `need`, never silently dropped.
+
+## References
+- GitHub, `spec-kit` spec template (User Scenarios & Testing, Requirements FR-NNN, Success Criteria) —
+  https://github.com/github/spec-kit/blob/main/templates/spec-template.md
+- GitHub, `spec-kit` — Spec-Driven Development methodology —
+  https://github.com/github/spec-kit/blob/main/spec-driven.md
+- Fission-AI, OpenSpec concepts (Purpose / Requirements / Scenarios, RFC 2119 strength keywords) —
+  https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md
+- Cucumber, "Gherkin Syntax" — https://cucumber.netlify.app/docs/gherkin/

package/templates/skills/write-tests/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: write-tests
+description: Write unit/integration tests test-first, one behaviour per test, red-green-refactor.
+capability: testing
+inputs: Acceptance criteria or a spec section, and the code under test (or the stub it will be written against).
+outputs: Test files (red then green) plus a pass/fail report for the covered behaviours.
+standard: TDD (Beck) + xUnit Test Patterns
+---
+# Write tests
+
+Test-first authoring of unit and integration tests, one behaviour at a time. End-to-end tests are a
+separate scope — use the `write-e2e-tests` skill for those; do not duplicate that work here.
+
+## When to use
+Whenever a piece of behaviour (a function, method, module, or the interaction of a few collaborators
+without crossing a real network/DB/UI boundary) needs to be implemented or changed, or when the
+workflow reaches a testing step for unit/integration coverage.
+
+## Method
+Apply Kent Beck's red-green-refactor loop per behaviour, structuring each test per Meszaros's
+xUnit Test Patterns:
+
+1. **Pick one behaviour.** Take the next acceptance criterion or edge case not yet covered. If it
+   needs more than one sentence to describe, it is more than one test — split it.
+2. **Red.** Write a test that fails for the right reason (the behaviour doesn't exist yet, not a typo
+   or setup bug). Give it a descriptive name stating the behaviour and condition, e.g.
+   `returns_empty_list_when_input_is_empty` or `throws_when_amount_is_negative` — not `test1` or
+   `testFoo`.
+3. **Structure with Arrange-Act-Assert** (Bill Wake / Beck): set up inputs and collaborators (Arrange),
+   invoke exactly the one thing under test (Act), check the outcome (Assert). No conditionals, loops,
+   or try/catch-as-control-flow inside a test — a test with logic in it is itself untested code
+   (Meszaros, *Obscure Test*). Prefer one focused assertion or a tight cluster checking one outcome;
+   avoid *Assertion Roulette* (many unrelated asserts with no way to tell which one failed) and
+   *Eager Test* (one test exercising several behaviours at once).
+4. **Green.** Write the minimum production code to pass the test — resist adding behaviour the test
+   doesn't require yet.
+5. **Refactor.** With the test green, remove duplication and improve naming in both test and production
+   code, in small steps, re-running the test after each. Never refactor and add behaviour in the same
+   step.
+6. **Repeat** for the next behaviour, including edge cases (empty/null/zero, boundary values, invalid
+   input, error/exception paths) — not just the happy path — until every acceptance criterion is
+   covered. Keep each test independent: no shared mutable fixture state and no ordering dependency
+   between tests (Meszaros, *Interacting Tests* / *Test Run Wars*).
+7. Choose the lowest level that gives honest confidence: unit-test pure logic in isolation; use a thin
+   integration test only for the seam where two real collaborators must be checked together (e.g. a
+   repository against a real schema). If the behaviour requires a live UI, network, or full-stack
+   boundary, hand off to `write-e2e-tests` instead of stretching a unit test to cover it.
+
+## Output contract
+Test files committed alongside the code, one file per unit under test following the project's test
+naming convention, red commit(s) allowed only transiently before the corresponding green commit. Report
+progress with granular, one-line-at-a-time writes and the `::spectoflow` sentinel:
+
+```
+::spectoflow role=testing kind=progress msg=<behaviour> red
+::spectoflow role=testing kind=progress msg=<behaviour> green
+::spectoflow role=testing kind=report msg=<N passed>/<N total>, 0 failed, 0 skipped
+```
+
+A suite left red or with a skipped test is reported as such, never silently marked done.
+
+## Quality bar
+- [ ] Every acceptance criterion has at least one test; meaningful edge cases (empty/null, boundary,
+      error paths) are covered, not just the happy path.
+- [ ] Each test covers exactly one behaviour and is named for that behaviour and its condition.
+- [ ] Each test follows Arrange-Act-Assert with no branching/looping logic inside the test body.
+- [ ] No Assertion Roulette (unrelated asserts bundled) and no Eager Test (one test, many behaviours).
+- [ ] Tests are independent — no shared mutable state, no required run order, no real secrets or live
+      external endpoints.
+- [ ] The full suite is green before reporting done; nothing is skipped or commented out to get there.
+
+## References
+- Kent Beck, *Test-Driven Development: By Example* (Addison-Wesley, 2002) — red/green/refactor.
+- Kent Beck, "Canon TDD" — https://tidyfirst.substack.com/p/canon-tdd
+- Martin Fowler, "Test Driven Development" — https://www.martinfowler.com/bliki/TestDrivenDevelopment.html
+- Gerard Meszaros, *xUnit Test Patterns: Refactoring Test Code* (Addison-Wesley, 2007) —
+  http://xunitpatterns.com/ ; "Assertion Roulette" http://xunitpatterns.com/Assertion%20Roulette.html ;
+  "Obscure Test" http://xunitpatterns.com/Obscure%20Test.html ; test smell catalog
+  http://xunitpatterns.com/TestSmells.html
+- Bill Wake, "3A – Arrange, Act, Assert" (2001) — https://xp123.com/3a-arrange-act-assert/

package/templates/workflow.md

@@ -0,0 +1,15 @@
+# Active workflow
+
+The enabled steps below define how work flows for this project. Check = enabled; uncheck or remove a
+line to change the pipeline (you can also edit this from the dashboard). This file is the single
+source of truth for the workflow.
+
+- [x] Brainstorm {cap:intake skill:brainstorm}
+- [x] Analysis {cap:analysis skill:analyze-requirements}
+- [x] Spec {cap:analysis skill:write-spec}
+- [x] Plan {cap:planning skill:write-plan}
+- [x] Develop {cap:implementation skill:implement}
+- [x] Unit tests {cap:testing skill:write-tests}
+- [ ] Integration tests (optional) {cap:testing skill:write-e2e-tests}
+- [ ] End-to-end tests (optional) {cap:testing skill:write-e2e-tests}
+- [x] Review {cap:quality skill:code-review}