User Journey: Curating External Practice into Governance
| Field | Value |
|---|---|
| Status | DRAFT |
| Implementation Status | VISION (target-state proposal; not current runtime reality) |
| Date | 2026-02-17 |
| Primary Contexts | Governance, Curation, Charter |
| Supporting Contexts | Orchestration, Agent Profiles, Tool Selection |
| Related Spec / ADR | Proposed ADR: 2026-02-17-1-explicit-governance-layer-model (not present in this branch) |
Scenario
A lead developer discovers an external practice (for example, ZOMBIES TDD) and wants it to become standard behavior for implementation agents in their Spec Kitty project.
The system should support this as a pull-based flow:
- capture the external idea as a curated candidate,
- adapt and classify it into Spec Kitty doctrine concepts,
- activate it through charter-level governance selection,
- and reflect it in implementation behavior.
Actors
| # | Actor | Type | Persona | Role in Journey |
|---|---|---|---|---|
| 1 | Lead Developer | human |
Lead Developer | Identifies external practice and approves adoption |
| 2 | AI Agent | llm |
AI Collaboration Agent | Performs curation analysis and proposes doctrine mapping |
| 3 | Spec-Kitty CLI | system |
Spec Kitty CLI Runtime | Stores curation artifacts, updates governance artifacts, validates schemas |
Preconditions
- Project has
doctrine/structure initialized. - Charter exists and is project authority for governance selection.
- Schema validation tests are available in
tests/. - Lead developer has identified an external source to curate.
Journey Map
| Phase | Actor(s) | System | Key Events |
|---|---|---|---|
| 1. Candidate Capture | Lead Developer ↔ AI Agent | Create import candidate record with source/provenance | ImportCandidateCreated |
| 2. Classification | AI Agent | Map external idea to target concept (paradigm/directive/tactic/template) | ImportCandidateClassified |
| 3. Adaptation | AI Agent ↔ Lead Developer | Propose adapted wording and constraints for Spec Kitty canon | ImportCandidateAdapted |
| 4. Governance Integration | AI Agent | Add/update doctrine artifacts and profile defaults | GovernanceArtifactsUpdated |
| 5. Charter Selection | Lead Developer ↔ AI Agent | Activate selected doctrine assets and profile/tool scope in charter | CharterSelectionsUpdated |
| 6. Validation | Spec-Kitty CLI | Run schema and consistency validation in tests/CI | GovernanceValidationPassed |
| 7. Operational Use | AI Agent | Implementation runs with newly activated behavior | BehaviorActivatedForImplementation |
Coordination Rules
- External practices are never adopted directly; they must enter through
ImportCandidate. - Classification and adaptation must be explicit before activation.
- Charter is the only project-level authority for activation.
- Schema validation must pass before behavior is considered active.
- If adaptation is ambiguous, stop and request developer confirmation.
Responsibilities
Spec-Kitty CLI (Local Runtime)
- Persist curation records and governance artifact updates.
- Validate artifacts against schemas.
- Expose failures as actionable QA errors.
AI Agent (LLM Context)
- Analyze source practice and extract applicable concepts.
- Propose mapping and adapted doctrine representation.
- Update mission-adjacent behavior via doctrine + charter (not by embedding ad hoc behavior in mission text).
Lead Developer (Human Authority)
- Approve/reject curation mapping and adaptation.
- Decide activation scope via charter selections.
- Confirm final adoption into project standards.
Scope: MVP
In Scope
- Candidate-based curation flow for one external source at a time.
- Mapping to at least one doctrine concept (
ParadigmorDirectiveorTactic). - Charter update for selected profiles and available tools.
- Schema validation pass/fail gate.
Out of Scope (Deferred)
- Automatic harvesting from web/catalogs.
- Bulk multi-candidate ranking/prioritization.
- Organization-wide multi-repo rollout orchestration.
Required Event Set
| # | Event | Emitted By | Phase |
|---|---|---|---|
| 1 | ImportCandidateCreated |
AI Agent | 1 |
| 2 | ImportCandidateClassified |
AI Agent | 2 |
| 3 | ImportCandidateAdapted |
AI Agent | 3 |
| 4 | GovernanceArtifactsUpdated |
AI Agent | 4 |
| 5 | CharterSelectionsUpdated |
AI Agent | 5 |
| 6 | GovernanceValidationPassed |
CLI | 6 |
| 7 | BehaviorActivatedForImplementation |
AI Agent | 7 |
Acceptance Scenarios
ZOMBIES TDD adopted as implementation behavior Given a lead developer provides a ZOMBIES TDD source, when an import candidate is curated, classified, adapted, and approved, then doctrine artifacts are updated, and charter selections activate the behavior for implementation profiles.
Invalid artifact blocked by schema gate Given a malformed curation or doctrine artifact, when validation runs, then activation is blocked and actionable validation errors are reported.
Charter authority enforced Given doctrine artifacts exist but charter selections are not updated, when implementation runs, then the new behavior is not considered active for project execution.
Design Decisions
| Decision | Rationale | ADR |
|---|---|---|
| Curation is candidate-first | Preserves provenance and explicit adaptation | pending (2026-02-17-1 proposed) |
| Charter is activation authority | Keeps per-project governance explicit and auditable | pending (2026-02-17-1 proposed) |
| Schema validation is required pre-activation | Provides early QA guardrail for governance changes | pending (2026-02-17-1 proposed) |
Product Alignment
This journey operationalizes the governance-layer model by showing how external practices become project behavior through curation + charter selection rather than ad hoc mission prompt edits.