chore: cutover from bmad to superpowers workflow

Distills the bmad-era PRD / architecture / epics into a single
docs/engineering.md (185 lines) covering project intent, the six
CI-enforced invariants with rationale, the five protocol seams,
the exception contract, current + planned module layout, testing
patterns, the optional-extras pattern, the remaining 27-story
roadmap, and a pointer to deferred-work.md.

Moves prd.md, architecture.md, epics.md, both product briefs, and
the per-story specs (1-1 through 1-5 + sprint-status.yaml) into
docs/archive/ with a README framing them as historical reference.

Rewrites CLAUDE.md "Project Overview" to point at engineering.md
and the new docs/superpowers/{specs,plans}/ flow. Updates the
stale `base-client/docs/architecture.md` pointer in "When in
doubt" to engineering.md + archive. All other operational
sections (commands, invariants, conventions, module layout,
seams, testing) are kept verbatim.

Also drops context7.json (no longer needed).

No source / test / CI changes. 157 tests still pass at 100%
coverage; ruff and ty clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: lesnik512

CLAUDE.md

@@ -6,15 +6,14 @@ Guidance for AI agents (Claude Code, etc.) working in this repository.
 
 `httpware` is a Python async HTTP client framework for building resilient service clients. It supersedes `community-of-python/base-client` and ships under the `modern-python` org. The framework owns the abstraction layer above the underlying HTTP client (`httpx2` by default); consumers never import the transport.
 
-**Source-of-truth planning artifacts** live in this repo under `docs/`:
+**Where to find what:**
 
-- `docs/prd.md` — Product Requirements Document (47 FRs, 25 NFRs)
-- `docs/architecture.md` — 12 architectural decisions, 5 protocol seams, full module layout
-- `docs/epics.md` — 6 epics, 32 stories with Given/When/Then acceptance criteria
-- `docs/product-brief-httpware.md` — executive brief (history of how the project was scoped)
-- `docs/product-brief-httpware-distillate.md` — PRD-ready detail pack with verified facts, API patterns, performance specifics, rejected alternatives, open questions
+- [`docs/engineering.md`](docs/engineering.md) — the distilled design reference: invariants and *why*, the five protocol seams, exception contract, module layout, testing patterns, optional-extras pattern, remaining roadmap. Read this before adding any new module or extension point.
+- [`docs/deferred-work.md`](docs/deferred-work.md) — review-surfaced items that are real but not actionable now.
+- [`docs/superpowers/specs/`](docs/superpowers/specs/) and [`docs/superpowers/plans/`](docs/superpowers/plans/) — per-feature design specs and implementation plans (active work).
+- [`docs/archive/`](docs/archive/) — historical bmad-era planning bundle (PRD, architecture, epics, product briefs, per-story specs for 1-1 through 1-5). Consult only for original rationale or specific FR/NFR citations.
 
-Stories under active dev live in `docs/stories/`. (Initial planning artifacts were authored in the predecessor repo `community-of-python/base-client` and copied here at the end of Story 1.1; both copies are kept in sync until base-client is archived.)
+**Per-feature workflow:** brainstorming → spec in `docs/superpowers/specs/` → writing-plans → plan in `docs/superpowers/plans/` → executing-plans (or subagent-driven-development) → requesting-code-review → finishing-a-development-branch. Topic slugs are kebab-case descriptions (`msgspec-decoder-adapter`), not story IDs.
 
 ## Commands
 
@@ -100,5 +99,5 @@ Five documented internal boundaries. AI agents must respect them — never cross
 
 ## When in doubt
 
-- Check the architecture document (`base-client/docs/architecture.md`) before adding a new module or extension point.
+- Check [`docs/engineering.md`](docs/engineering.md) before adding a new module or extension point; `docs/archive/architecture.md` has the deeper historical rationale if needed.
 - Surface ambiguity as a documentation gap rather than improvising.

context7.json

@@ -0,0 +1,17 @@
+# Archive
+
+This directory contains the bmad-era planning artifacts for `httpware`:
+
+- `prd.md` — 47 functional and 25 non-functional requirements.
+- `architecture.md` — twelve architectural decisions, the five protocol seams, full module layout.
+- `epics.md` — six epics with 32 stories.
+- `product-brief-httpware.md` and `product-brief-httpware-distillate.md` — executive brief and detail pack from the predecessor `community-of-python/base-client` scoping exercise.
+- `stories/` — per-story specs (1-1 through 1-5) and the retired `sprint-status.yaml`.
+
+These files are **historical reference, not authoritative**. The load-bearing decisions were distilled into [`../engineering.md`](../engineering.md) on 2026-05-31 when the project switched workflows from bmad to superpowers. Consult these archived files only when you need:
+
+- Original rationale behind a decision (e.g., "why did we choose `httpx2` over `aiohttp`?").
+- The specific FR/NFR numbers that a future spec wants to cite (e.g., `archive/prd.md#NFR-12`).
+- The Given/When/Then acceptance criteria from a completed story.
+
+For everything else — invariants, seams, module layout, conventions, the remaining roadmap — read `../engineering.md` and `../../CLAUDE.md`.