Spec Kitty Architecture: User Journeys
Current state (2026-09-30). Every design journey below is a 2.x-era vision snapshot from early 2026 and has been retired as historical; none has been re-validated against the 4.x CLI. The active cycle is 4.0.0 — see the 4.0.0 roadmap. New journeys still follow the template and lifecycle described here.
This directory contains user journey descriptions that contribute to the evolution and refinement of the Spec Kitty system.
These are architectural design artifacts — they capture how users (human and AI) interact with spec-kitty across phases, system boundaries, and coordination concerns. They inform mission design, mission templates, and CLI command structure.
Purpose
User journeys in this directory serve three roles:
- Design input — They describe how the system should work, driving mission specifications and implementation priorities.
- Alignment check — They validate that new capabilities serve the end-to-end user experience, not just isolated commands.
- Living documentation — They evolve as spec-kitty evolves, capturing the intended workflow at each stage of the system's maturity.
Template
Journeys follow the User Journey Template, which captures:
- Actors (with type annotations and persona links)
- Journey Map (phase table with events)
- Coordination Rules
- Responsibilities (split by system boundary)
- Acceptance Scenarios (BDD format)
- Design Decisions (linked to ADRs)
Persona references in actor tables should point to
docs/context/audience/internal/*.md or docs/context/audience/external/*.md.
Status Lifecycle
| Status | Meaning |
|---|---|
DRAFT |
Proposed journey, under discussion |
REVIEW |
Journey reviewed against implementation feasibility |
ACCEPTED |
Journey approved as target design — drives mission work |
IMPLEMENTED |
Journey fully realized in spec-kitty commands and workflows |
Implementation Status Field
Each journey metadata table also carries an Implementation Status field:
| Value | Meaning |
|---|---|
VISION |
Target-state proposal; not yet runtime-implemented |
PARTIAL |
Parts implemented, parts still target-state |
REALITY |
Matches currently supported runtime behavior |
Live
No design journey is currently live. The user-facing walkthrough of spec-kitty init followed by
charter interview and charter generate is product documentation, not a design journey; it now
lives in the guides as
How to Initialize a Project and Author Its Charter.
Historical (2.x-era vision snapshots)
| Journey | Status | Implementation Status | Description |
|---|---|---|---|
| Project Onboarding & Bootstrap | DRAFT | VISION | New project setup: init → bootstrap (vision + charter) → first mission |
| System Architecture Design | DRAFT | VISION | Architectural structure and boundary design after bootstrap |
| System Design & Shared Understanding | DRAFT | VISION | Design mission flow for glossary, journeys, and ADR alignment |
| Curating External Practice into Governance | DRAFT | VISION | Pull-based adoption flow for external practices (e.g., ZOMBIES TDD) via curation + charter activation |
| Governance Mission Creation and Charter Operations | DRAFT | VISION | Bootstrap flow for governance mission: curation, charter review/alter/sync, and directive-compliant traceability |
Relationship to Other Architecture Artifacts
- ADRs (
docs/adr/, one folder per era) — Individual design decisions; journeys may reference multiple ADRs - Audience personas (
docs/context/audience/) — Deep stakeholder/actor profiles linked from journey actor tables - Mission specs (
kitty-specs/) — Per-mission specifications; journeys span multiple missions - Mission Templates (
src/specify_cli/missions/) — Journeys inform which missions and phases are needed
Evaluation
See the 2.x User Journey Evaluation (historical) for the canonical-vs-initiative assessment.