diff --git a/.claude/skills/spec-driven-blueprint/README.md b/.claude/skills/spec-driven-blueprint/README.md new file mode 100644 index 0000000000..09db59bcf4 --- /dev/null +++ b/.claude/skills/spec-driven-blueprint/README.md @@ -0,0 +1,85 @@ +# spec-driven-blueprint skill + +A Claude Code skill that walks the user through Spec-Driven Development end-to-end and produces a single consolidated `BLUEPRINT.md` that drives implementation. + +## What this skill does + +Instead of running `/speckit.constitution`, `/speckit.specify`, `/speckit.clarify`, `/speckit.plan`, and `/speckit.tasks` as separate steps and ending up with five files, this skill runs one guided interview and produces **one** Markdown file. The blueprint contains: + +- Constitutional gates the implementer must respect +- Prioritized user scenarios (P1/P2/P3) with Given/When/Then acceptance criteria +- Functional requirements (with at most 3 `[NEEDS CLARIFICATION]` markers) +- Measurable, technology-agnostic success criteria +- Technical context (language, deps, storage, performance, scale) +- Concrete project structure +- A strict, sequenced task list organized by user story +- Dependencies, parallel opportunities, and an implementation strategy + +The blueprint is designed to be handed to an implementing agent (or `/speckit.implement`) without further preparation. + +## Files in this skill + +| File | Purpose | +|----------------------------|---------------------------------------------------------------------| +| `SKILL.md` | The skill itself — instructions Claude follows when invoked. | +| `blueprint-template.md` | The empty blueprint structure the skill fills in. | +| `example-blueprint.md` | A worked example (URL shortener) for pattern-matching. | +| `README.md` | This file — installation and usage notes. | + +## Installing + +### Option A: Project-scoped (lives with the repo) + +The skill is already at `.claude/skills/spec-driven-blueprint/SKILL.md`. Anyone who clones the repo and runs Claude Code from its root gets the skill automatically. + +### Option B: Personal scope (use it on any project) + +Copy the directory into your personal Claude config: + +```bash +mkdir -p ~/.claude/skills +cp -r .claude/skills/spec-driven-blueprint ~/.claude/skills/ +``` + +### Option C: Plugin + +If you maintain a Claude plugin, drop this skill directory into the plugin's `skills/` folder and ship it like any other capability. + +## Using the skill + +Once installed, trigger it with any of these: + +- "Walk me through spec-driven development for [feature idea]." +- "Create an SDD blueprint for [feature idea]." +- "Drive the development of [feature] with a spec." +- "Guide me through the spec-kit workflow." + +Claude will run the 14-phase workflow defined in `SKILL.md`: + +1. Detect environment (spec-kit repo? constitution present?). +2. Capture the idea. +3. Generate short-name and confirm output path. +4. Constitutional gates. +5. User scenarios (WHAT). +6. Functional requirements + entities. +7. Clarify (only if `[NEEDS CLARIFICATION]` markers remain). +8. Success criteria. +9. Technical context (HOW, high level). +10. Constitution re-check. +11. Project structure. +12. Tasks. +13. Write `BLUEPRINT.md`. +14. Self-validate, then report. + +The output is written to `specs/-/BLUEPRINT.md` in spec-kit-initialized repos, or `./BLUEPRINT.md` otherwise. The path is always confirmed with the user before writing. + +## Why one file instead of five + +- Easier to review in a PR description or chat thread. +- Easier to hand to an implementing agent without losing cross-references. +- Easier to keep in sync — one file evolves, no risk of drift between `spec.md` and `plan.md`. +- Easier to lift sections back out into separate spec-kit artifacts later if needed; the section structure mirrors the spec-kit templates. + +## Relationship to spec-kit core commands + +This skill **does not replace** spec-kit. If your team already uses `/speckit.specify`, `/speckit.plan`, `/speckit.tasks` and the discrete-artifact workflow, keep using them. This skill is for the case where you want a single consolidated blueprint — for personal projects, quick prototypes, blog posts, design reviews, or feeding another agent. diff --git a/.claude/skills/spec-driven-blueprint/SKILL.md b/.claude/skills/spec-driven-blueprint/SKILL.md new file mode 100644 index 0000000000..ff0d7ae161 --- /dev/null +++ b/.claude/skills/spec-driven-blueprint/SKILL.md @@ -0,0 +1,251 @@ +--- +name: spec-driven-blueprint +description: Guide a user through Spec-Driven Development (SDD) end-to-end and produce a single consolidated Markdown blueprint that drives implementation. Use when the user wants to plan a new feature with the full SDD discipline (constitution → specify → clarify → plan → tasks) and end up with one executable artifact instead of running multiple slash commands. Trigger phrases include "drive development with a spec", "create an SDD blueprint", "walk me through spec-driven development", "guide me through the spec-kit workflow". +--- + +# Spec-Driven Blueprint Skill + +Take a fuzzy product idea and turn it into a single, executable Markdown blueprint that an LLM (or human) can implement straight through. This skill consolidates the spec-kit workflow — constitution, specify, clarify, plan, tasks — into one guided interview and one output file: `BLUEPRINT.md`. + +## When to Use + +- The user has an idea but no concrete spec, plan, or task list yet. +- The user wants the rigor of spec-kit (`/speckit.specify`, `/speckit.plan`, `/speckit.tasks`) without invoking each command separately. +- The user wants a single Markdown file they can hand to another agent, paste into a PR description, or check into the repo. +- The repo is or is not a spec-kit project — this skill works in either case. + +## When NOT to Use + +- The user has already run `/speckit.specify` and friends and wants to keep using those commands. Defer to them. +- The task is a one-line bug fix or trivial change — no blueprint needed. +- The user just wants a code change right now and explicitly does not want planning artifacts. + +## Core Output: `BLUEPRINT.md` + +This skill produces **one file**: `BLUEPRINT.md` (path configurable, default at the repo root or under `specs/-/BLUEPRINT.md` if the repo is spec-kit-initialized). The file is structured so that each section can be lifted into spec-kit's own templates if desired, but is also self-contained. + +The blueprint sections, in order: + +1. **Header** — feature name, short-name, date, status, source idea quote. +2. **Constitutional Gates** — the non-negotiable principles this feature respects (Library-First, CLI Interface, Test-First, Simplicity ≤3 projects, Anti-Abstraction, Integration-First). Each gate is a checkbox the implementer can verify. +3. **User Scenarios** — prioritized user stories (P1/P2/P3...) with Given/When/Then acceptance scenarios. P1 must be an independently shippable MVP slice. +4. **Edge Cases** — explicit list of boundary conditions and failure modes. +5. **Functional Requirements** — `FR-001`, `FR-002`, ... each testable. `[NEEDS CLARIFICATION: ...]` markers where unavoidable (max 3). +6. **Key Entities** — domain concepts (no implementation detail). +7. **Success Criteria** — measurable, technology-agnostic outcomes (`SC-001`, `SC-002`, ...). +8. **Assumptions** — defaults the user accepted by not specifying otherwise. +9. **Technical Context** — language, primary deps, storage, testing, target platform, project type, performance goals, constraints, scale. +10. **Project Structure** — concrete directory tree for source and tests. +11. **Tasks** — sequenced, dependency-ordered, organized by user story. Strict format: `- [ ] T### [P?] [USx?] Description with file path`. +12. **Dependencies & Execution Order** — phase dependencies, story dependencies, parallel opportunities. +13. **Implementation Strategy** — MVP-first, incremental delivery, parallel team variants. +14. **Open Questions** — any unresolved `[NEEDS CLARIFICATION]` items, escalated for the user. + +## Workflow + +Make a TodoWrite list of the phases below and work them in order. Mark each phase complete as you go — never skip ahead even if you think you have enough information. + +### Phase 0 — Detect Environment + +1. Check whether the repo is spec-kit-initialized: does `.specify/` or `templates/spec-template.md` exist? +2. Check whether `memory/constitution.md` or `.specify/memory/constitution.md` exists. If yes, **read it** and treat its principles as binding for this blueprint. +3. Decide the output path: + - Spec-kit repo: `specs/-/BLUEPRINT.md` (compute `NNN` by scanning existing `specs/` dirs, three-digit zero-padded). + - Otherwise: `./BLUEPRINT.md` at the repo root. +4. Tell the user the detected mode and the planned output path. Ask them to confirm or override. + +### Phase 1 — Capture the Idea + +Ask the user, in one message, for: + +- **One-paragraph problem statement**: What are they trying to build, for whom, and why now? +- **Existing constraints**: Any tech stack mandate, deadline, compliance requirement, or platform target they already know? +- **What's explicitly out of scope** for this slice? + +Do not ask follow-ups yet. Capture the answer verbatim into a working buffer; you will quote it in the blueprint header. + +### Phase 2 — Generate Short Name and Confirm Output Path + +From the problem statement, derive a 2-4 word kebab-case short-name (action-noun: `add-user-auth`, `fix-payment-timeout`, `analytics-dashboard`). Show it to the user with the resolved output path; let them override before continuing. + +### Phase 3 — Constitution Gates + +If a constitution file was found in Phase 0, list its principles back to the user and ask: "Any gate you want to relax or add for this feature?" + +If no constitution exists, propose the spec-kit defaults: + +- Library-First (every feature begins as a standalone library) +- CLI Interface (text in/out, JSON support) +- Test-First (NON-NEGOTIABLE — tests written, approved, and failing before implementation) +- Simplicity (≤3 projects, no future-proofing) +- Anti-Abstraction (use frameworks directly, single model representation) +- Integration-First Testing (real environments over mocks, contract tests mandatory) + +The user can drop or modify any of these. Record the final list — every gate becomes a checkbox in the blueprint's Constitutional Gates section. + +### Phase 4 — User Scenarios (the WHAT) + +Draft 2-5 user stories with priorities. Rules: + +- **P1 must be an independently shippable MVP** — if you implement only P1, the user gets real value. +- Each story has: brief title, narrative paragraph, "Why this priority", "Independent Test" description, and 1-3 Given/When/Then acceptance scenarios. +- Stay at the user-value level — no implementation detail. If you find yourself writing "use Redis" or "POST /api/foo", stop and rewrite at the user level. + +Show the draft to the user. Ask: "Are these the right priorities? Add, remove, or re-rank any." + +### Phase 5 — Functional Requirements & Entities + +From the user stories, derive: + +- **Functional Requirements** (`FR-001`, ...): each must be testable and unambiguous. Use "System MUST...", "Users MUST be able to...". +- **Key Entities** (if data is involved): name + 1-line description + key attributes. **No** schema, no field types, no SQL. +- **Edge Cases**: boundary conditions, failure modes, empty states. + +When the user prompt genuinely doesn't specify something, prefer **informed defaults** and record them in the Assumptions section. Only emit `[NEEDS CLARIFICATION: ]` markers when: + +- The choice significantly impacts scope or UX. +- Multiple reasonable interpretations exist with materially different implications. +- No reasonable default exists. + +**Hard cap: 3 `[NEEDS CLARIFICATION]` markers across the whole blueprint.** If you generate more, keep only the 3 highest-impact and resolve the rest with informed defaults. + +### Phase 6 — Clarify (only if needed) + +If any `[NEEDS CLARIFICATION]` markers remain, present them to the user as a numbered set of questions, **all in one message**, formatted as: + +```markdown +## Question N: + +**Context**: + +**What we need to know**: + +**Suggested Answers**: + +| Option | Answer | Implications | +|--------|--------|--------------| +| A | ... | ... | +| B | ... | ... | +| C | ... | ... | +| Custom | Provide your own | ... | + +**Your choice**: _waiting for response_ +``` + +Wait for the user's response, then replace each `[NEEDS CLARIFICATION]` with the chosen answer. Do not proceed to Phase 7 with any markers remaining. + +### Phase 7 — Success Criteria + +Generate 3-6 measurable, technology-agnostic outcomes. Each must be: + +- **Measurable**: time, percentage, count, rate. +- **Technology-agnostic**: no framework, language, or database name. +- **User/business-facing**: not "API < 200ms" but "users see results instantly". +- **Verifiable** without knowing the implementation. + +Examples: + +- ✅ "Users can complete checkout in under 3 minutes." +- ✅ "95% of searches return results in under 1 second." +- ❌ "Redis cache hit rate above 80%." (technology-specific) + +### Phase 8 — Technical Context (the HOW, high level) + +Now ask the user about implementation. Single message, structured: + +- **Language/Version** (e.g., Python 3.12, TypeScript 5.4, Rust 1.75) +- **Primary Dependencies / Frameworks** +- **Storage** (Postgres, SQLite, files, none) +- **Testing framework** +- **Target Platform** (Linux server, browser, iOS, etc.) +- **Project Type** (single library, CLI, web app, mobile + API, ...) +- **Performance Goals** +- **Constraints** (memory, latency, offline, budget) +- **Scale/Scope** (users, data volume, features) + +Anything the user leaves blank → mark as `NEEDS CLARIFICATION` in Technical Context **only** (these don't count against the 3-marker cap from Phase 5; they're tech-context unknowns, not spec ambiguity). + +### Phase 9 — Constitution Re-check + +Walk through each gate from Phase 3. For each: + +- **Pass** → leave the checkbox unchecked (implementer will check) and move on. +- **Fail / Justified violation** → add a row to the Complexity Tracking table with `Violation | Why Needed | Simpler Alternative Rejected Because`. + +If you cannot justify a gate failure, **do not proceed**. Tell the user the gate is failing and ask them to either accept the simpler alternative or provide justification. + +### Phase 10 — Project Structure + +Pick the layout that matches Project Type: + +- **Single project** (default): `src/{models,services,cli,lib}` + `tests/{contract,integration,unit}` +- **Web app**: `backend/src/{models,services,api}` + `frontend/src/{components,pages,services}` + tests in each +- **Mobile + API**: `api/...` + `ios/` or `android/` + +Render the concrete tree. No `Option 1/2/3` labels — just the chosen tree. + +### Phase 11 — Tasks + +Generate a task list organized by user story. Hard rules: + +- **Phase 1 — Setup** (no story label): project init, dependencies, lint config. +- **Phase 2 — Foundational** (no story label): blocking prerequisites for all stories. Database schema, auth framework, base models, error handling, logging. **Nothing user-story-specific.** This phase blocks all subsequent phases. +- **Phase 3+ — One phase per user story** in priority order (P1 → P2 → P3 ...). Each story phase has a checkpoint at the end stating the story is now independently testable. +- **Final phase — Polish & Cross-Cutting**: docs, perf, security hardening, quickstart validation. + +Every task strictly follows: `- [ ] T### [P?] [USx?] Description with exact file path`. + +- `T###` is sequential across the whole blueprint. +- `[P]` only when the task touches different files than other `[P]` tasks in the same phase and has no dependency on incomplete tasks. +- `[USx]` is required for user-story phase tasks, forbidden for Setup/Foundational/Polish. +- Tests, when included, come **before** implementation tasks they cover. + +After the task list, add **Dependencies & Execution Order** (phase deps, story deps, intra-story rules, parallel opportunities) and **Implementation Strategy** (MVP-first, incremental, parallel-team). + +### Phase 12 — Write `BLUEPRINT.md` + +Write the file to the path confirmed in Phase 2 / Phase 0. Use the structure laid out in **Core Output**. Use absolute paths when calling Write. + +### Phase 13 — Validate + +Self-review the blueprint against this checklist (this is your unit-test for the document — fix any failures before reporting back): + +- [ ] No implementation details leaked into User Scenarios, Functional Requirements, or Success Criteria. +- [ ] At most 3 `[NEEDS CLARIFICATION]` markers in spec sections (Phases 4–7). +- [ ] Every Functional Requirement is testable. +- [ ] Every Success Criterion is measurable and technology-agnostic. +- [ ] P1 user story is independently shippable as an MVP. +- [ ] Every task has an ID, a file path, a checkbox, and (if a story task) a `[USx]` label. +- [ ] No task in Setup or Foundational has a `[USx]` label. +- [ ] No story task in a later phase blocks an earlier P1 task. +- [ ] Constitutional Gates section lists every principle from Phase 3. +- [ ] Complexity Tracking exists if any gate is violated; absent otherwise. +- [ ] Technical Context fields are filled or marked `NEEDS CLARIFICATION`. + +Run up to 3 self-review iterations. After 3, if anything still fails, list the failing items in the blueprint's **Open Questions** section and warn the user. + +### Phase 14 — Report + +Reply to the user with: + +- Path to `BLUEPRINT.md`. +- Counts: user stories (by priority), functional requirements, success criteria, tasks (total + per phase). +- List of any `[NEEDS CLARIFICATION]` markers still present. +- Suggested next step: "Hand this blueprint to an implementing agent, or run `/speckit.implement` if this is a spec-kit project pointed at this directory." + +Keep the report under 200 words. + +## Design Principles for the Skill Itself + +- **Ask in batches, not drip-by-drip.** Each phase asks for everything it needs in one message and waits. +- **Default aggressively, ask sparingly.** The 3-marker cap is intentional — guess the rest with industry-standard defaults and document them in Assumptions. +- **WHAT before HOW.** Phases 4-7 stay user-facing. Phase 8+ go technical. Don't let tech bleed into spec. +- **One file out.** Resist the temptation to scatter `spec.md`, `plan.md`, `tasks.md`. The point of this skill is consolidation. +- **Test the document like code.** Phase 13's checklist is the unit test. The blueprint isn't done until it passes. + +## Reference Files + +- `blueprint-template.md` (next to this SKILL.md): the full template structure with all sections, ready to be filled in. +- `example-blueprint.md`: a worked example for a small feature, for the model to pattern-match against. + +When writing the final `BLUEPRINT.md`, start from `blueprint-template.md` and fill in section by section — do not invent a different structure. diff --git a/.claude/skills/spec-driven-blueprint/blueprint-template.md b/.claude/skills/spec-driven-blueprint/blueprint-template.md new file mode 100644 index 0000000000..f76c92e5de --- /dev/null +++ b/.claude/skills/spec-driven-blueprint/blueprint-template.md @@ -0,0 +1,364 @@ +# Blueprint: [FEATURE NAME] + +**Short Name**: `[short-name]` +**Date**: [YYYY-MM-DD] +**Status**: Draft | In Review | Approved | Implementing | Done +**Source Idea**: > [Quote the user's original problem statement here, verbatim] + +--- + +## 1. Constitutional Gates + +These principles are binding for this feature. Each is a checkbox the implementer verifies as they go. If a gate cannot be passed, document the violation in §13 Complexity Tracking. + +- [ ] **Library-First**: Every feature begins as a standalone library with a clear purpose, self-contained and independently testable. +- [ ] **CLI Interface**: Every library exposes its functionality via a text-in/text-out CLI with JSON support. +- [ ] **Test-First (NON-NEGOTIABLE)**: Tests are written, approved, and confirmed failing before any implementation code is written. +- [ ] **Simplicity**: ≤3 projects, no future-proofing, no speculative abstractions. +- [ ] **Anti-Abstraction**: Use frameworks directly; one model representation; no wrapper layers without justification. +- [ ] **Integration-First Testing**: Tests use realistic environments (real DB, real services) over mocks; contract tests mandatory. + + + +--- + +## 2. User Scenarios + +User stories are prioritized as user journeys, ordered by importance. Each story is **independently testable** — implementing only that story still delivers a viable MVP slice. + +### User Story 1 — [Brief Title] (Priority: P1) — MVP + +[One-paragraph narrative description of the user journey in plain language.] + +**Why this priority**: [Why P1; what value it unlocks first] + +**Independent Test**: [How to verify this story works on its own — concrete action and observable outcome] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] +2. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +### User Story 2 — [Brief Title] (Priority: P2) + +[Narrative] + +**Why this priority**: [...] +**Independent Test**: [...] + +**Acceptance Scenarios**: + +1. **Given** [...], **When** [...], **Then** [...] + +--- + +### User Story 3 — [Brief Title] (Priority: P3) + +[Narrative] + +**Why this priority**: [...] +**Independent Test**: [...] + +**Acceptance Scenarios**: + +1. **Given** [...], **When** [...], **Then** [...] + + + +--- + +## 3. Edge Cases + +- What happens when [boundary condition]? +- How does the system handle [error scenario]? +- What happens at [scale limit]? +- Behavior when [external dependency unavailable]? + +--- + +## 4. Functional Requirements + +Each requirement must be testable and unambiguous. Use `[NEEDS CLARIFICATION: ]` only when no reasonable default exists. **Maximum 3 markers across the whole document.** + +- **FR-001**: System MUST [capability] +- **FR-002**: System MUST [capability] +- **FR-003**: Users MUST be able to [interaction] +- **FR-004**: System MUST [data behavior] +- **FR-005**: System MUST [policy / non-functional behavior] + + + +--- + +## 5. Key Entities + +Domain concepts, no implementation detail. No field types, no schemas, no SQL. + +- **[Entity 1]**: [What it represents, key attributes at the conceptual level] +- **[Entity 2]**: [What it represents, relationships to other entities] + +--- + +## 6. Success Criteria + +Measurable, technology-agnostic outcomes. Each must be verifiable without knowing the implementation. + +- **SC-001**: [Time / completion metric, e.g., "Users complete onboarding in under 2 minutes"] +- **SC-002**: [Volume / scale metric, e.g., "System handles 1000 concurrent users without degradation"] +- **SC-003**: [Quality / satisfaction metric, e.g., "90% of users complete primary task on first attempt"] +- **SC-004**: [Business metric, e.g., "Reduce support tickets in category X by 50%"] + +--- + +## 7. Assumptions + +Defaults adopted because the source idea didn't specify. The implementer can challenge any of these. + +- [Assumption about target users, e.g., "Users have stable internet connectivity"] +- [Assumption about scope, e.g., "Mobile support is out of scope for this slice"] +- [Assumption about environment, e.g., "Existing authentication service will be reused"] +- [Assumption about data, e.g., "Data retention follows industry-standard 90 days"] + +--- + +## 8. Technical Context + +| Field | Value | +|-------------------------|--------------------------------------------------| +| Language / Version | [e.g., Python 3.12 / TypeScript 5.4 / Rust 1.75] | +| Primary Dependencies | [e.g., FastAPI, React 18, Tokio] | +| Storage | [e.g., PostgreSQL 16 / SQLite / files / N/A] | +| Testing Framework | [e.g., pytest, vitest, cargo test] | +| Target Platform | [e.g., Linux server / Browser / iOS 17+] | +| Project Type | [single library / CLI / web app / mobile + API] | +| Performance Goals | [e.g., 1000 req/s, 60 fps, 10k lines/sec] | +| Constraints | [e.g., <200ms p95, <100MB RAM, offline-capable] | +| Scale / Scope | [e.g., 10k users, 1M LOC, 50 screens] | + +--- + +## 9. Project Structure + +### Documentation (this feature) + +```text +specs/-/ +├── BLUEPRINT.md # This file +└── (legacy spec-kit artifacts may live here too — they're optional) +``` + +### Source Code (repository root) + + + +```text +# Single project +src/ +├── models/ +├── services/ +├── cli/ +└── lib/ + +tests/ +├── contract/ +├── integration/ +└── unit/ +``` + +```text +# Web application +backend/ +├── src/ +│ ├── models/ +│ ├── services/ +│ └── api/ +└── tests/ + +frontend/ +├── src/ +│ ├── components/ +│ ├── pages/ +│ └── services/ +└── tests/ +``` + +```text +# Mobile + API +api/ +└── (same as backend above) + +ios/ or android/ +└── (platform-specific feature modules and tests) +``` + +**Structure Decision**: [State which option you picked and why, referencing real directory names you'll create] + +--- + +## 10. Tasks + +Tasks are organized by user story so each story can be built, tested, and shipped independently. Format is strict: `- [ ] T### [P?] [USx?] Description with exact file path`. + +- `[P]` = parallelizable with other `[P]` tasks in the same phase (no shared files, no dependency on incomplete tasks). +- `[USx]` = required for user-story-phase tasks; forbidden in Setup, Foundational, and Polish. + +### Phase 1 — Setup (Shared Infrastructure) + +- [ ] T001 Create project structure per §9 +- [ ] T002 Initialize [language] project with [framework] dependencies +- [ ] T003 [P] Configure linting and formatting tools +- [ ] T004 [P] Configure CI scaffolding (lint + test stubs) + +### Phase 2 — Foundational (Blocking Prerequisites) + +> **CRITICAL**: No user-story work may begin until this phase is complete. + +- [ ] T005 Set up database schema and migrations framework +- [ ] T006 [P] Implement authentication / authorization framework +- [ ] T007 [P] Set up routing and middleware structure +- [ ] T008 Create base entities/models that all stories depend on +- [ ] T009 Configure error handling and structured logging +- [ ] T010 Configure environment variable loading + +**Checkpoint**: Foundation ready — user-story phases can now run in parallel (if staffed). + +### Phase 3 — User Story 1: [Title] (P1) 🎯 MVP + +**Goal**: [What this story delivers] +**Independent Test**: [How to verify it works on its own] + +#### Tests for User Story 1 (write these first; they MUST FAIL before implementation) + +- [ ] T011 [P] [US1] Contract test for [interface] in tests/contract/test_.py +- [ ] T012 [P] [US1] Integration test for [user journey] in tests/integration/test_.py + +#### Implementation for User Story 1 + +- [ ] T013 [P] [US1] Create [Entity1] model in src/models/.py +- [ ] T014 [P] [US1] Create [Entity2] model in src/models/.py +- [ ] T015 [US1] Implement [Service] in src/services/.py (depends on T013, T014) +- [ ] T016 [US1] Implement [endpoint/feature] in src//.py +- [ ] T017 [US1] Add validation and error handling +- [ ] T018 [US1] Add logging for User Story 1 operations + +**Checkpoint**: User Story 1 is fully functional and independently testable. + +### Phase 4 — User Story 2: [Title] (P2) + +**Goal**: [...] +**Independent Test**: [...] + +#### Tests for User Story 2 (optional — only if requested) + +- [ ] T019 [P] [US2] ... + +#### Implementation for User Story 2 + +- [ ] T020 [P] [US2] ... +- [ ] T021 [US2] ... + +**Checkpoint**: User Stories 1 and 2 both work independently. + +### Phase 5 — User Story 3: [Title] (P3) + +[same pattern] + +### Phase N — Polish & Cross-Cutting + +- [ ] T0XX [P] Documentation updates in docs/ +- [ ] T0XX Performance optimization across stories +- [ ] T0XX Security hardening +- [ ] T0XX Run quickstart validation against §6 Success Criteria + +--- + +## 11. Dependencies & Execution Order + +### Phase Dependencies + +- **Setup (Phase 1)** — no deps; can start immediately. +- **Foundational (Phase 2)** — depends on Setup; **blocks all user stories**. +- **User Stories (Phase 3+)** — all depend on Foundational. Stories may then run in parallel or sequentially in priority order. +- **Polish (Final)** — depends on all included user stories. + +### User Story Dependencies + +- **US1 (P1)**: Starts after Foundational. No deps on other stories. +- **US2 (P2)**: Starts after Foundational. May integrate with US1 but must remain independently testable. +- **US3 (P3)**: Starts after Foundational. May integrate with US1/US2 but must remain independently testable. + +### Within Each User Story + +- Tests (when present) MUST be written and FAIL before implementation begins. +- Models before services; services before endpoints; core before integration. +- A story is "complete" only when its checkpoint criteria are met. + +### Parallel Opportunities + +- All `[P]` Setup tasks can run together. +- All `[P]` Foundational tasks can run together (within Phase 2). +- After Foundational completes, all user-story phases can run in parallel given enough capacity. +- Within a story: all `[P]` tests run together; all `[P]` models run together. + +--- + +## 12. Implementation Strategy + +### MVP First (User Story 1 only) + +1. Phase 1 — Setup +2. Phase 2 — Foundational +3. Phase 3 — User Story 1 +4. **STOP. Validate User Story 1 independently.** +5. Ship / demo. + +### Incremental Delivery + +1. Setup + Foundational → foundation ready. +2. + User Story 1 → ship MVP. +3. + User Story 2 → ship. +4. + User Story 3 → ship. +5. Each story adds value without breaking earlier stories. + +### Parallel Team Strategy + +1. Whole team completes Setup + Foundational together. +2. Once Foundational is green: + - Dev A: User Story 1 + - Dev B: User Story 2 + - Dev C: User Story 3 +3. Stories integrate independently via the contracts established in Phase 2. + +--- + +## 13. Complexity Tracking + +> Fill this **only** if a Constitutional Gate (§1) is violated and you justify the violation. Otherwise leave blank. + +| Violation | Why Needed | Simpler Alternative Rejected Because | +|----------------------------|-----------------------------|---------------------------------------| +| [e.g., 4th project] | [the actual driver] | [why 3 projects can't work here] | +| [e.g., Repository pattern] | [the specific problem] | [why direct DB access falls short] | + +--- + +## 14. Open Questions + +> Items that remain unresolved after Phase 13 self-review. Each is a `[NEEDS CLARIFICATION]` that the implementer must resolve before the corresponding tasks can begin. + +- [ ] Q1: [the question, with the section it blocks] +- [ ] Q2: ... + + + +--- + +## 15. Change Log + +| Date | Author | Change | +|------------|--------|-------------------------------------------| +| YYYY-MM-DD | [name] | Initial blueprint generated by skill. | diff --git a/.claude/skills/spec-driven-blueprint/example-blueprint.md b/.claude/skills/spec-driven-blueprint/example-blueprint.md new file mode 100644 index 0000000000..674a70b4c7 --- /dev/null +++ b/.claude/skills/spec-driven-blueprint/example-blueprint.md @@ -0,0 +1,316 @@ +# Blueprint: URL Shortener Service + +**Short Name**: `url-shortener` +**Date**: 2026-05-06 +**Status**: Draft +**Source Idea**: > "I want a small URL shortening service. Users paste a long URL, get back a short code, and visiting the short code redirects them. Track click counts so I can see which links are popular. Personal project, single Linux server, won't get more than a few thousand links." + +--- + +## 1. Constitutional Gates + +- [ ] **Library-First**: URL-shortening logic and click-tracking each live as standalone libraries. +- [ ] **CLI Interface**: A `urlshort` CLI exposes shorten, lookup, and stats commands with JSON output. +- [ ] **Test-First (NON-NEGOTIABLE)**: Tests written and failing before any implementation. +- [ ] **Simplicity**: ≤3 projects (single project here: `src/` + `tests/`). +- [ ] **Anti-Abstraction**: Use SQLite directly via the standard driver; no ORM. +- [ ] **Integration-First Testing**: Integration tests use a real SQLite file; contract tests for HTTP endpoints precede implementation. + +--- + +## 2. User Scenarios + +### User Story 1 — Shorten a URL and visit it (Priority: P1) — MVP + +A user pastes a long URL into a form, receives a short code, and visiting the short code redirects them to the original URL. + +**Why this priority**: Without this, the service has no reason to exist. This is the entire core loop. + +**Independent Test**: From a clean install, submit `https://example.com/very/long/path` to the shorten endpoint, receive a code, request `/`, and verify a 302 redirect to the original URL. + +**Acceptance Scenarios**: + +1. **Given** the service is running, **When** a user submits a valid URL to the shorten endpoint, **Then** the response includes a unique short code of 6-8 characters. +2. **Given** a previously shortened code, **When** a user visits `/`, **Then** they receive a 302 redirect to the original URL. +3. **Given** an invalid URL (e.g., not http/https), **When** a user submits it, **Then** the response is a 400 with a clear error message. + +--- + +### User Story 2 — See click counts per short code (Priority: P2) + +A user looks up the click count for any short code they created. + +**Why this priority**: Popularity tracking is the user's stated goal but is not on the critical redirect path; ship redirects first. + +**Independent Test**: Create a short code, visit it 5 times, query the stats endpoint for that code, verify the count is 5. + +**Acceptance Scenarios**: + +1. **Given** a short code has been visited N times, **When** the user requests its stats, **Then** the response shows `clicks: N`. +2. **Given** an unknown short code, **When** the user requests its stats, **Then** the response is a 404. + +--- + +### User Story 3 — List all shortened URLs (Priority: P3) + +A user can list every short code they've created with original URL and click count. + +**Why this priority**: Convenience for a personal-use tool; not required for either core loop or stats lookup. + +**Independent Test**: Create three codes, list them, verify all three appear with correct original URLs and counts. + +**Acceptance Scenarios**: + +1. **Given** at least one code exists, **When** the user requests the list endpoint, **Then** the response is a JSON array of `{code, original_url, clicks, created_at}` objects ordered newest-first. + +--- + +## 3. Edge Cases + +- What happens when the same long URL is submitted twice? (Return existing code or generate new one — see FR-005.) +- What happens on a short-code collision when generating? (Retry with a new code; cap retries at 5 then 500.) +- What happens when a redirect target becomes invalid (DNS fails)? (Out of scope — service still issues the redirect; the browser handles failure.) +- What happens at scale beyond stated assumptions? (Out of scope; stated cap is "few thousand links".) + +--- + +## 4. Functional Requirements + +- **FR-001**: System MUST accept a URL via an HTTP POST endpoint and return a unique short code. +- **FR-002**: System MUST validate that submitted URLs use the `http` or `https` scheme; reject all others with 400. +- **FR-003**: System MUST redirect requests for `/` to the original URL with HTTP 302 when the code exists. +- **FR-004**: System MUST return HTTP 404 for unknown short codes. +- **FR-005**: System MUST return the existing short code when a previously submitted URL is submitted again (no duplicate codes for the same URL). +- **FR-006**: System MUST increment a click counter every time a short code is resolved successfully. +- **FR-007**: System MUST expose a stats endpoint returning `{code, original_url, clicks, created_at}` for a given code. +- **FR-008**: System MUST expose a list endpoint returning all codes ordered by `created_at` descending. +- **FR-009**: System MUST persist data across restarts. + +--- + +## 5. Key Entities + +- **Link**: A single shortened URL. Holds the short code, the original URL, the creation timestamp, and the click count. + +--- + +## 6. Success Criteria + +- **SC-001**: A user can shorten a URL and see the redirect work in under 5 seconds end-to-end on a fresh install. +- **SC-002**: The redirect path returns within 100ms at the 95th percentile under a load of 100 requests/second. +- **SC-003**: Click counts are accurate to within 1% under concurrent load (100 simultaneous redirects of the same code). +- **SC-004**: The service survives restart without losing any links or click counts. + +--- + +## 7. Assumptions + +- Single-user (or trusted multi-user) personal service; no authentication required. +- Single Linux server; no horizontal scaling. +- Total link count stays under 10,000 (well below the SQLite practical ceiling). +- Short codes are case-sensitive base62 strings, 6-8 characters. +- Default retention is indefinite; no expiry mechanism in this slice. + +--- + +## 8. Technical Context + +| Field | Value | +|-------------------------|----------------------------------------| +| Language / Version | Python 3.12 | +| Primary Dependencies | FastAPI, uvicorn, sqlite3 (stdlib) | +| Storage | SQLite, single file `data/links.db` | +| Testing Framework | pytest, httpx (test client) | +| Target Platform | Linux server (any distro with Python) | +| Project Type | Single project (web service + CLI) | +| Performance Goals | 100 req/s sustained on the redirect path | +| Constraints | <100ms p95 redirect; single binary deploy preferred | +| Scale / Scope | <10,000 total links, <1M total clicks | + +--- + +## 9. Project Structure + +### Documentation (this feature) + +```text +specs/001-url-shortener/ +└── BLUEPRINT.md +``` + +### Source Code (repository root) + +```text +src/ +├── models/ +│ └── link.py +├── services/ +│ ├── shortener.py +│ └── stats.py +├── cli/ +│ └── urlshort.py +└── api/ + └── routes.py + +tests/ +├── contract/ +│ ├── test_shorten_endpoint.py +│ ├── test_redirect_endpoint.py +│ ├── test_stats_endpoint.py +│ └── test_list_endpoint.py +├── integration/ +│ ├── test_shorten_and_redirect.py +│ ├── test_click_counting.py +│ └── test_list_links.py +└── unit/ + └── test_code_generation.py +``` + +**Structure Decision**: Single-project layout. Service is small enough that splitting backend/CLI into separate projects would violate the Simplicity gate. + +--- + +## 10. Tasks + +### Phase 1 — Setup + +- [ ] T001 Create project structure per §9 (src/, tests/, data/) +- [ ] T002 Initialize Python 3.12 project with pyproject.toml; add FastAPI, uvicorn, pytest, httpx +- [ ] T003 [P] Configure ruff (lint) and black (format) +- [ ] T004 [P] Add Makefile with `test`, `lint`, `run` targets + +### Phase 2 — Foundational + +- [ ] T005 Create SQLite schema migration in src/db/schema.sql (links table: code TEXT PRIMARY KEY, original_url TEXT, clicks INTEGER, created_at TEXT) +- [ ] T006 [P] Implement DB connection helper in src/db/connection.py +- [ ] T007 [P] Implement structured logging in src/logging_config.py +- [ ] T008 Wire FastAPI app skeleton in src/api/app.py with health endpoint + +**Checkpoint**: Foundation ready — user-story phases can begin. + +### Phase 3 — User Story 1: Shorten and visit (P1) 🎯 MVP + +**Goal**: Submit a URL, receive a short code, visit the code, get redirected. +**Independent Test**: See §2 US1. + +#### Tests for User Story 1 + +- [ ] T009 [P] [US1] Contract test for POST /shorten (valid URL → 200 + code) in tests/contract/test_shorten_endpoint.py +- [ ] T010 [P] [US1] Contract test for POST /shorten (invalid URL → 400) in tests/contract/test_shorten_endpoint.py +- [ ] T011 [P] [US1] Contract test for GET / (known → 302) in tests/contract/test_redirect_endpoint.py +- [ ] T012 [P] [US1] Contract test for GET / (unknown → 404) in tests/contract/test_redirect_endpoint.py +- [ ] T013 [P] [US1] Integration test for shorten-then-redirect happy path in tests/integration/test_shorten_and_redirect.py + +#### Implementation for User Story 1 + +- [ ] T014 [P] [US1] Create Link model in src/models/link.py +- [ ] T015 [US1] Implement code generation (base62, 6-8 chars, collision retry) in src/services/shortener.py (depends on T014) +- [ ] T016 [US1] Implement POST /shorten route in src/api/routes.py (depends on T015) +- [ ] T017 [US1] Implement GET / redirect route in src/api/routes.py (depends on T015) +- [ ] T018 [US1] Add URL scheme validation and 400 handling + +**Checkpoint**: US1 fully functional — service can shorten and redirect. + +### Phase 4 — User Story 2: Click counts (P2) + +**Goal**: Read click counts per short code. +**Independent Test**: See §2 US2. + +#### Tests for User Story 2 + +- [ ] T019 [P] [US2] Contract test for GET /stats/ in tests/contract/test_stats_endpoint.py +- [ ] T020 [P] [US2] Integration test for click counter under concurrent load in tests/integration/test_click_counting.py + +#### Implementation for User Story 2 + +- [ ] T021 [US2] Add atomic click-count increment to GET / handler in src/api/routes.py (modifies T017's handler) +- [ ] T022 [US2] Implement stats lookup in src/services/stats.py +- [ ] T023 [US2] Implement GET /stats/ route in src/api/routes.py + +**Checkpoint**: US2 functional — stats reflect real visit counts. + +### Phase 5 — User Story 3: List all (P3) + +**Goal**: List every link. +**Independent Test**: See §2 US3. + +#### Tests for User Story 3 + +- [ ] T024 [P] [US3] Contract test for GET /links in tests/contract/test_list_endpoint.py +- [ ] T025 [P] [US3] Integration test for list ordering in tests/integration/test_list_links.py + +#### Implementation for User Story 3 + +- [ ] T026 [US3] Implement list query in src/services/stats.py +- [ ] T027 [US3] Implement GET /links route in src/api/routes.py + +**Checkpoint**: All three stories independently functional. + +### Phase 6 — Polish & Cross-Cutting + +- [ ] T028 [P] Implement urlshort CLI wrapping shorten/stats/list in src/cli/urlshort.py +- [ ] T029 [P] Write README.md with quickstart matching §6 SC-001 +- [ ] T030 Run load test to verify SC-002 (100 req/s, <100ms p95) +- [ ] T031 Add structured access logging on the redirect path + +--- + +## 11. Dependencies & Execution Order + +### Phase Dependencies + +- Setup (1) → Foundational (2) → US1 / US2 / US3 (3-5) → Polish (6). +- US2 modifies a file owned by US1 (routes.py); US1 must complete first or US2 must merge into US1's handler carefully. + +### User Story Dependencies + +- US1: independent. +- US2: shares routes.py with US1; sequence US1 → US2. +- US3: shares routes.py with US1 and US2; sequence after US2. + +### Parallel Opportunities + +- All `[P]` tests within a story can run concurrently. +- T014 and T015 cannot — T015 imports the Link model. +- Polish tasks T028 and T029 can run in parallel. + +--- + +## 12. Implementation Strategy + +### MVP First + +1. Phases 1-3. +2. Validate US1 against acceptance scenarios. +3. Ship. + +### Incremental Delivery + +1. Foundation + US1 → working shortener. +2. + US2 → analytics. +3. + US3 → admin convenience. +4. + Polish → CLI and ops readiness. + +### Parallel Team Strategy + +Single-developer project; sequential execution is fine. + +--- + +## 13. Complexity Tracking + +> No gate violations. Section intentionally empty. + +--- + +## 14. Open Questions + +> No unresolved clarifications. Section intentionally empty. + +--- + +## 15. Change Log + +| Date | Author | Change | +|------------|--------|-----------------------------------------| +| 2026-05-06 | skill | Initial blueprint generated by skill. |