Implementation Plan: Doctrine Enrichment — Frontend, Brownfield, BDD, and Tactic Normalization

Branch: feature/doctrine-enrichment-bdd-profiles → merges to main Date: 2026-04-26 Spec: spec.md

Summary

Add 2 new agent profiles (Frontend Freddy, Node Norris), normalize the shipped tactic directory into 4 category subdirectories, add 7 new/adapted doctrine artifacts (tactics, paradigm, procedure), enrich 5 existing profiles with BDD and bug-fixing references, and add 2 generic doctrine acceptance tests. All artifacts are YAML files in src/doctrine/; no Python source changes are required except the two new test files.

Technical Context

Language/Version: Python 3.11+ (test code only); YAML 1.1 for all doctrine artifacts Primary Dependencies: ruamel.yaml (doctrine loader), pydantic (schema validation), pytest with @pytest.mark.doctrine and @pytest.mark.fast markers Storage: Filesystem — src/doctrine/ tree; no database Testing: pytest -m doctrine — existing schema validation tests cover all new YAML. Two new test files in tests/doctrine/. Target Platform: Cross-platform (Linux/macOS); artifacts are plain YAML files Performance Goals: All doctrine tests in fast bucket must complete under 1 second each Constraints:

  • No Python loader code changes (C-001)
  • Tactic IDs unchanged when files move (C-002)
  • No local filesystem paths in shipped YAML (C-006)
  • Attribution to patterns.sddevelopment.be in notes field only (C-006)
  • Frontend Freddy and Node Norris must mutually exclude each other's domain in avoidance-boundary (C-007)

Charter Check

Charter is minimal (software-dev-default template, DIR-001 only). No conflicts with the spec. DIR-001 (Architectural Integrity) is satisfied: all new artifacts follow existing schemas and the rglob loader handles subdirectories without modification.

Project Structure

Documentation (this mission)

kitty-specs/doctrine-enrichment-frontend-brownfield-normalization-01KQ48XA/
├── plan.md              ← this file
├── research.md          ← Phase 0 output
├── spec.md
└── tasks/               ← WP files (generated by /spec-kitty.tasks)

Source Code Targets

src/doctrine/
├── agent_profiles/shipped/
│   ├── frontend-freddy.agent.yaml          ← NEW (FR-001)
│   ├── node-norris.agent.yaml              ← NEW (FR-002)
│   ├── implementer-ivan.agent.yaml         ← MODIFIED (FR-007)
│   ├── reviewer-renata.agent.yaml          ← MODIFIED (FR-006, FR-011)
│   ├── architect-alphonso.agent.yaml       ← MODIFIED (FR-011)
│   └── java-jenny.agent.yaml              ← MODIFIED (FR-011)
├── paradigms/shipped/
│   └── behaviour-driven-development.paradigm.yaml  ← NEW (FR-009)
├── procedures/shipped/
│   └── bdd-scenario-lifecycle.procedure.yaml       ← NEW (FR-010)
└── tactics/shipped/
    ├── behavior-driven-development.tactic.yaml     ← MODIFIED in place (FR-012)
    ├── analysis/                                   ← NEW DIR (FR-004)
    │   ├── code-documentation-analysis.tactic.yaml ← NEW (FR-003)
    │   └── terminology-extraction-mapping.tactic.yaml ← NEW (FR-003)
    │   └── [~13 moved tactics]                     ← MOVED (FR-004)
    ├── architecture/                               ← NEW DIR (FR-004)
    │   ├── reference-architectural-patterns.tactic.yaml ← NEW (FR-005)
    │   ├── development-bdd.tactic.yaml             ← NEW (FR-005)
    │   └── [~12 moved tactics]                     ← MOVED (FR-004)
    ├── communication/                              ← NEW DIR (FR-004)
    │   └── [~7 moved tactics]                      ← MOVED (FR-004)
    └── testing/                                    ← NEW DIR (FR-004)
        ├── bug-fixing-checklist.tactic.yaml        ← NEW (FR-007)
        ├── test-readability-clarity-check.tactic.yaml ← NEW (FR-006)
        └── [~15 moved tactics]                     ← MOVED (FR-004)

src/doctrine/_reference/
└── quickstart-agent-augmented-development/candidates/
    ├── tactic-code-documentation-analysis.import.yaml     ← NEW provenance
    ├── tactic-terminology-extraction-mapping.import.yaml  ← NEW provenance
    └── tactic-development-bdd.import.yaml                 ← NEW provenance

tests/doctrine/
├── test_profile_inheritance.py      ← MODIFIED (FR-008 — add generic specialization test)
└── test_bdd_lifecycle_coverage.py   ← NEW (FR-008 acceptance test, or extend existing file)

Complexity Tracking

No charter violations. The development-bdd.tactic.yaml (new, architecture-focused) coexists with behavior-driven-development.tactic.yaml (existing, technique-focused). This is intentional: they serve different concerns. The implementer must ensure both IDs are unique and their purposes are differentiated in their purpose fields.

Work Package Sequencing

Phase 1 — Foundation (parallelizable, no inter-WP file conflicts)

WPScopeFRs
WP01Tactic directory normalization — move ~47 existing .tactic.yaml files into 4 category subdirsFR-004
WP02New brownfield analysis tactics + provenance importsFR-003
WP03New architecture tactics (reference-architectural-patterns, development-bdd) + enriched BDD tactic notesFR-005, FR-012
WP04New testing tactics (bug-fixing-checklist, test-readability-clarity-check)FR-006 partial, FR-007 partial
WP05BDD paradigm + bdd-scenario-lifecycle procedureFR-009, FR-010

WP01 moves existing files; WP02–WP05 create new files in the same directories. In parallel worktrees they do not conflict (WP01 moves existing files; WP02–05 create brand-new files). Merge order: WP01 first, then WP02–05 can merge in any order.

Phase 2 — Profiles (can parallelize WP06 and WP07; WP08 depends on Phase 1 merge)

WPScopeFRsDepends on
WP06Frontend Freddy profile (complete, including BDD enrichment)FR-001, FR-011 partialWP04, WP05 merged
WP07Node Norris profile (complete, including BDD enrichment)FR-002, FR-011 partialWP04, WP05 merged
WP08Enrich existing profiles: implementer-ivan, reviewer-renata, architect-alphonso, java-jennyFR-007, FR-006, FR-011WP03, WP04, WP05 merged

Phase 3 — Tests (depends on all profiles complete)

WPScopeFRsDepends on
WP09Generic profile specialization tactic inheritance testFR-008WP06, WP07, WP08 merged

Implementation Notes per WP

WP01 — Tactic Normalization

Move the following existing files (IDs unchanged, id field in YAML is canonical):

→ testing/ acceptance-test-first, atdd-adversarial-acceptance, black-box-integration-testing, formalized-constraint-testing, function-over-form-testing, mutation-testing-workflow, no-parallel-duplicate-test-runs, quality-gate-verification, tdd-red-green-refactor, test-boundaries-by-responsibility, testing-select-appropriate-level, test-minimisation, test-pyramid-progression, test-to-system-reconstruction, zombies-tdd

→ analysis/ ammerse-impact-analysis, analysis-extract-before-interpret, bounded-context-canvas-fill, bounded-context-identification, connascence-analysis, context-boundary-inference, context-mapping-classification, entity-value-object-classification, premortem-risk-identification, requirements-validation-workflow, reverse-speccing, safe-to-fail-experiment, strategic-domain-classification

→ communication/ adr-drafting-workflow, decision-marker-capture, documentation-curation-audit, glossary-curation-interview, stakeholder-alignment, traceable-decisions, usage-examples-sync

→ architecture/ aggregate-boundary-design, anti-corruption-layer, architecture-diagram-review-checklist, atomic-design-review-checklist, atomic-state-ownership, c4-zoom-in-architecture-documentation, compositional-stream-boundaries, cross-cutting-state-via-store, dependency-hygiene, domain-event-capture, language-driven-design, problem-decomposition

Remain in shipped/ root (no clear category fit): avoid-gold-plating, autonomous-operation-protocol, behavior-driven-development (enriched separately in WP03), change-apply-smallest-viable-diff, code-review-incremental, easy-to-change, eisenhower-prioritisation, input-validation-fail-fast, locality-of-change, occurrence-classification-workflow, review-intent-and-risk-first, secure-design-checklist, stopping-conditions, work-package-completion-validation

Exit gate: pytest -m doctrine green; len(repo.load_all()) >= 47 (exact count confirmed at WP start).

WP02 — Brownfield Analysis Tactics

Two new YAML files in shipped/analysis/:

  • code-documentation-analysis.tactic.yaml — adapted from quickstart; steps: extract terminology from code, extract from docs, identify semantic clusters, produce glossary candidates. notes field: Adapted from patterns.sddevelopment.be
  • terminology-extraction-mapping.tactic.yaml — adapted from quickstart; steps: identify source materials, extract terms, map relationships, assign ownership. notes field: Adapted from patterns.sddevelopment.be

Two provenance import files in src/doctrine/_reference/quickstart-agent-augmented-development/candidates/.

WP03 — New Architecture Tactics + BDD Tactic Enrichment

New YAML in shipped/architecture/:

  • reference-architectural-patterns.tactic.yaml — steps: characterize problem domain, enumerate candidate patterns, score against constraints (coupling/scalability/operational complexity), select and document in an ADR
  • development-bdd.tactic.yaml — purpose: "Use BDD-style behavioral contracts to define system boundaries and acceptance criteria before implementation." Distinct from behavior-driven-development (which covers the technique); this tactic is architecture-level — used during design to express observable behavioral contracts. notes field: Adapted from patterns.sddevelopment.be

Modify shipped/behavior-driven-development.tactic.yaml in-place (stays in root):

  • Extend notes with toolchain landscape summary (Cucumber-JVM/Cucumber-JS/Behave/SpecFlow; Playwright integration; Serenity BDD narrative reports; custom DSL trade-offs). Attribution line: Source: patterns.sddevelopment.be/primers/toolchain-and-automation/bdd
  • Extend failure_modes with: rubber-stamp scenarios, shared mutable state between scenarios, orphaned step definitions
  • Add references: bdd-scenario-lifecycle procedure, behaviour-driven-development paradigm

WP04 — New Testing Tactics

New YAML in shipped/testing/:

  • bug-fixing-checklist.tactic.yaml — language-agnostic; enforces test-first bug fixing: write a failing test to reproduce the defect before touching production code. Steps: read and reproduce (write failing test first), characterize (confirm behavior gap), implement minimal fix, verify full suite green, document fix rationale
  • test-readability-clarity-check.tactic.yaml — dual-perspective reconstruction: (1) read only test code and reconstruct system understanding; (2) compare against specification. Findings: tests that do not enable reconstruction are insufficient documentation. notes field: Adapted from patterns.sddevelopment.be

WP05 — BDD Paradigm + Procedure

New shipped/behaviour-driven-development.paradigm.yaml:

schema_version: "1.0"
id: behaviour-driven-development
name: Behaviour-Driven Development
summary: >
  BDD is a collaboration practice built on three cyclical phases: Discovery
  (structured Three Amigos conversations produce concrete behavioral examples),
  Formulation (examples are expressed as human-readable Given/When/Then
  specifications), and Automation (formulated specs become executable tests that
  serve as living documentation). BDD does not replace unit testing — it sits
  above the test pyramid and is reserved for behaviors with cross-functional
  business value. Distinct from Specification by Example (the broader technique);
  BDD specifies the collaboration model and mandates executable automation as
  the canonical form of the specification.
directive_refs:
  - DIRECTIVE_034
  - DIRECTIVE_037

New shipped/bdd-scenario-lifecycle.procedure.yaml:

  • Entry: validated canonical example set from example-mapping-workshop
  • Exit: each example is a passing executable scenario; feature file readable by non-technical audience
  • Steps: (1) Express in Gherkin; (2) Validate readability; (3) Wire step definitions; (4) Red → implement → green; (5) Publish to living documentation report
  • Anti-patterns: imperative Gherkin (UI clicks not business intent), rubber-stamp scenarios, shared mutable state, orphaned step definitions
  • References: example-mapping-workshop, behavior-driven-development, acceptance-test-first, DIRECTIVE_034, DIRECTIVE_037

WP06 — Frontend Freddy Profile

Full profile at shipped/frontend-freddy.agent.yaml. Key fields:

  • profile-id: frontend-freddy | specializes-from: implementer-ivan | roles: [implementer]
  • applies_to_languages: [javascript, typescript, html, css]
  • avoidance-boundary names server-side Node.js, HTTP handler authoring, database access, UX/UI design decisions, and managing other agents
  • self-review-protocol: lint → tsc --noEmit → vitest → playwright smoke → axe-core → bundle size gate
  • directive-references: DIR-010, DIR-024, DIR-030, DIR-034
  • tactic-references: behavior-driven-development, bdd-scenario-lifecycle

WP07 — Node Norris Profile

Full profile at shipped/node-norris.agent.yaml. Key fields:

  • profile-id: node-norris | specializes-from: implementer-ivan | roles: [implementer]
  • applies_to_languages: [javascript, typescript]
  • avoidance-boundary names browser DOM and CSS, React/Vue/Svelte rendering, mobile UI, UX/UI design decisions, and managing other agents
  • self-review-protocol: lint → tsc --noEmit → vitest/jest → supertest integration → npm audit
  • directive-references: DIR-010, DIR-024, DIR-030, DIR-034
  • tactic-references: behavior-driven-development

WP08 — Enrich Existing Profiles

ProfileChanges
implementer-ivanAdd tactic-references: bug-fixing-checklist
reviewer-renataAdd tactic-references: test-readability-clarity-check, bdd-scenario-lifecycle; add paradigm ref: behaviour-driven-development
architect-alphonsoAdd paradigm ref: behaviour-driven-development; add procedure refs to example-mapping-workshop, bdd-scenario-lifecycle in context-sources.additional
java-jennyAdd paradigm ref: behaviour-driven-development; add tactic-references: behavior-driven-development, bdd-scenario-lifecycle; extend self-review-protocol with Cucumber-JVM/Serenity scenarios gate

All four profiles must pass pytest -m doctrine schema validation after changes.

WP09 — Generic Profile Specialization Inheritance Test

In tests/doctrine/test_profile_inheritance.py (or new sibling file):

@pytest.mark.doctrine
@pytest.mark.fast
def test_specializing_profiles_inherit_base_tactic_references(shipped_profile_repo, shipped_tactic_repo):
    """
    For every profile P that specializes-from base B:
    if B declares a tactic-reference with id T, P's resolved context must include T.
    """
    profiles = shipped_profile_repo.load_all()
    base_tactic_refs = {
        profile.id: {ref.id for ref in (profile.tactic_references or [])}
        for profile in profiles.values()
    }

    violations = []
    for profile in profiles.values():
        if not profile.specializes_from:
            continue
        base_id = profile.specializes_from
        if base_id not in base_tactic_refs:
            continue
        for tactic_id in base_tactic_refs[base_id]:
            own_refs = {ref.id for ref in (profile.tactic_references or [])}
            if tactic_id not in own_refs:
                violations.append(f"{profile.id} missing tactic '{tactic_id}' inherited from '{base_id}'")

    assert not violations, "\n".join(violations)

Note: this test is intentionally strict — specialist profiles must explicitly declare inherited tactic refs (or the resolution mechanism must surface them). If the profile loader already performs inheritance resolution, the test verifies the resolved result. The implementer should check the existing profile model's resolution behavior and adapt accordingly.