Spec Kitty Architecture: User Journeys
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 feature 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 feature specifications and implementation priorities.
- Alignment check — They validate that new features 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 feature 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 |
Index
| Journey | Status | Implementation Status | Description |
|---|---|---|---|
| Project Onboarding & Bootstrap | DRAFT | VISION | New project setup: init → bootstrap (vision + charter) → first feature |
| 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/2.x/) — Individual design decisions; journeys may reference multiple ADRs - Audience personas (
docs/context/audience/) — Deep stakeholder/actor profiles linked from journey actor tables - Feature Specs (
kitty-specs/) — Per-feature specifications; journeys span multiple features - Mission Templates (
src/specify_cli/missions/) — Journeys inform which missions and phases are needed
Evaluation
See 2.x User Journey Evaluation for canonical-vs-initiative assessment.