Versonas — discipline-focused virtual personas

Repo-wide documentation habits (single source of truth, link don’t duplicate) are summarized in Documentation structure — proposal.

Documentation map (Diátaxis-style)

Single source of truth for paths: Versona template index (source paths) — other pages summarize and link there.

Source layout (templates on disk)

Only versona-generic.mdc.template lives at the versona/ root. Every other versona-*.mdc.template lives under catalog/.

versona/
├── versona-generic.mdc.template          # optional Layer-0-only companion (baseline)
├── VERSONA-CONTRACT.md …                 # normative docs, README, _includes/, …
└── catalog/
    ├── ANCESTRY.md
    ├── TEMPLATE-INDEX.md
    ├── discipline/
    │   ├── engineering/                  # + family/versona-family-engineering.mdc.template
    │   ├── data/
    │   ├── product/
    │   ├── governance/
    │   └── cross-cutting/
    ├── meta/versona-sampling.mdc.template
    ├── workflow/versona-project-setup.mdc.template
    ├── workflow/versona-roadmap-gate.mdc.template
    ├── workflow/versona-cursor-rules-sync.mdc.template
    └── routing/versona-all.mdc.template

Family aggregators are a kind in the taxonomy, not a top-level folder next to discipline/: on disk they sit under catalog/discipline/<domain>/family/ (engineering, data, product).

How to find a template

• By domain (Engineering, Data, …): open catalog/discipline/<domain>/ for single-discipline templates; family rules are in that domain’s family/ subfolder.
• By kind (routing, meta, workflow): see section headings in Versona ancestry — kinds, domains, templates.
• Definitive path per file: find the basename in Versona template index (source paths).
• Copying into a consumer repo: drop the .template suffix; installed rule names stay flat (versona-se.mdc, …).

Framework (kinds, sessions, processes)

Normative concepts—Versona kinds, input/output interfaces, repeatable process docs, inter-Versona handoffs, session layout under forge-logs/versona/, and alignment with Ember Log and day journal—are in Versona framework — kinds, interfaces, processes, sessions. Cursor rule structure for discipline templates remains in Versona contract.

Ancestry and shared baseline

Kinds (discipline, routing, family aggregator, meta, workflow) and domains (Engineering, Data, Product, Governance, Cross-cutting) are mapped in Versona ancestry — kinds, domains, templates. Every versona-*.mdc.template includes a duplicated ## Baseline (inherited) block so a single attached rule stays self-contained (Cursor has no rule inheritance). The canonical snippet lives in GENERIC VERSONA BASELINE—edit there first, then propagate into templates. Optional: copy versona-generic.mdc.template (at this folder’s root) to .cursor/rules/ as a Layer-0-only companion to @ alongside a discipline Versona. All other versona-*.mdc.template files live under catalog/ (see Versona catalog).

How Versonas work

1. A decision point or working session needs a discipline lens (refinement, pre-build, pre-release, drafting, exploration).
2. The team identifies which discipline perspectives are relevant.
3. The appropriate Versonas are invoked (via Cursor rule or manual prompt).
4. Each Versona operates from its discipline’s perspective—via a §5 structured review when useful (Versona contract §5), or via other activities per Versona framework — kinds, interfaces, processes, sessions.
5. The team acts on results (concerns, drafts, handoffs), capturing decisions in the Ember Log when trade-offs or scope change.

Bridge-awareness

Each Versona template references its discipline's bridge document (*-SDLC-PDLC-BRIDGE.md). The bridge contains a phase alignment table that tells the Versona agent when its discipline is most relevant:

• Architecture Versona is strongest at phases A–C (discover, specify, design), lighter at D–F.
• Testing Versona activates at phases D–E (build, verify) and during Assay Gate.
• BA Versona is strongest at phases A–B (discover, specify) and at Review.

This phase-awareness lets Versonas calibrate review depth and other work based on the current Spark's phase prefix (discover:, build:, verify:, etc.).

Template catalog

Engineering family (7 disciplines)

Ancestry and when to invoke: Engineering family — Versona ancestry — versona-se as the shared craft ancestor, versona-family-engineering as the preferred default when multiple lenses may apply, specialists and handoffs.

Data family (2 disciplines)

Product family (5 disciplines)

Governance family (1 discipline)

Cross-cutting (2 disciplines)

Methodology / demo (5)

Family aggregators

Tasklets (example bundle)

Small single-operation Cursor rules and an installer script live in Forge tasklets — small Cursor operations. They demonstrate how a meta-Versona (e.g. Sampling) can chain tasklets before deeper discipline Versonas.

• Install: bash blueprints/sdlc/methodologies/forge/tasklets/install-tasklets.sh from the consuming repo root (requires blueprints/ submodule).
• Docs: Forge tasklets — small Cursor operations · Tasklet taxonomy
• Product globs: Recommended Cursor `globs` for Product Versonas
• Align rules with forge.config.yaml: Forge `forge.config.yaml` ↔ `.cursor/rules/` alignment

Discipline overlay (neutral tasklets + normative Versona)

Sampling Versona sequence (demo)

Where documentation is published

Adopting Versonas in a consuming repo

1. Recommended: From the consuming repo root, run ../setup/sync-forge-cursor-rules.sh sync --preset recommended (requires forge/forge.config.yaml and blueprints/). Quick ref: Cursor rules — quickstart (Forge + Versonas); full detail: Forge `forge.config.yaml` ↔ `.cursor/rules/` alignment. Use --dry-run to preview, --force only after reviewing diff / status. YAML-only install: sync sync with no --preset. Or copy templates manually to .cursor/rules/ (remove .template suffix).
2. Optional: sync … sync --preset full includes versona-generic.mdc.template and family aggregators; or copy individual templates.
3. Included in recommended preset: catalog/workflow/versona-project-setup.mdc.template (setup) — pair with ../setup/forge-setup.mdc.template for the questionnaire wizard.
4. Included in recommended preset: catalog/workflow/versona-roadmap-gate.mdc.template — roadmap quality gate (@versona-roadmap-gate).
5. Optional: Install the example tasklets + Sampling Versona via ../tasklets/install-tasklets.sh.
6. Included in recommended preset: catalog/workflow/versona-cursor-rules-sync.mdc.template — chat playbook for sync/diff commands (@versona-cursor-rules-sync).
7. Update globs: in each rule to match your project's file structure.
8. Configure which Versonas are active in forge.config.yaml (via the setup wizard).
9. Use family aggregators to activate discipline groups without configuring each individually.

See Versona contract for the standard structure discipline Versonas follow. See Versona framework — kinds, interfaces, processes, sessions for kinds, sessions, processes, and logging conventions. See Versona ancestry — kinds, domains, templates for the kind/domain tree and Versona template index (source paths) for every template source path.