Work Packages: Doctrine Org Init From Template

Inputs: Design documents from /kitty-specs/doctrine-org-init-from-template-01KXNA6P/ Prerequisites: plan.md (required), spec.md, research.md, data-model.md, contracts/, quickstart.md

Tests: Explicit ATDD coverage required (charter ATDD-first + existing CliRunner suite).

Organization: Fine-grained subtasks (Txxx) roll up into work packages (WPxx). Each work package must be independently deliverable and testable.

Prompt Files: Each work package references a matching prompt file in /tasks/ generated by /spec-kitty.tasks.

Audience: Operators who create their own doctrine via extended spec-kitty doctrine org init.

Path Conventions

  • Library: src/specify_cli/doctrine/template_render/
  • CLI: src/specify_cli/cli/commands/doctrine.py
  • Tests: tests/specify_cli/doctrine/, tests/cli/

Subtask Index

IDDescriptionWPParallel
T001RED: ORG_NAME / LOCAL_PATH validation unit testsWP01
T002Implement validation helpers + rule_id errorsWP01
T003RED: TEMPLATE parse + branch conflict unit testsWP01[P]
T004Implement local/git TEMPLATE resolve via GitSourceWP01
T005Package public types (RenderRequest, ResolvedTemplateSource)WP01
T006RED: .templateignore + built-in exclude copy testsWP02
T007Implement ignore matcher + full-tree copyWP02
T008RED: token substitute + leftover-token testsWP02[P]
T009Implement substitute walk + leftover assertWP02
T010Orchestrate validate→resolve→copy→substitute pipelineWP02
T011RED: CliRunner template-path + minimal-scaffold regressionWP03
T012Wire --template / --org-name / --local-path / --branch on org_initWP03
T013Error surfacing (NFR-001) + success output for render pathWP03

Work Package WP01: Validation & Template Resolve (Priority: P0)

Goal: Ship fail-closed ORG_NAME/LOCAL_PATH validation and local/git TEMPLATE resolve (including dual branch surface) as a testable doctrine library package. Independent Test: Unit tests pass for validation rule_ids, local path resolve, git resolve (mocked GitSource), and branch conflict detection without touching the CLI. Prompt: /tasks/WP01-validation-and-resolve.md Requirement Refs: FR-003, FR-004, FR-005, FR-006, FR-010, C-001, C-002, C-004

Included Subtasks

  • ✅ T001 RED: ORG_NAME / LOCAL_PATH validation unit tests
  • ✅ T002 Implement validation helpers + rule_id errors
  • ✅ T003 [P] RED: TEMPLATE parse + branch conflict unit tests
  • ✅ T004 Implement local/git TEMPLATE resolve via GitSource
  • ✅ T005 Package public types (RenderRequest, ResolvedTemplateSource)

Implementation Notes

  • Create src/specify_cli/doctrine/template_render/ package (validation.py, resolve.py, __init__.py exports).
  • ORG_NAME rules exactly match doctrine-template downstream contract (no sanitising).
  • LOCAL_PATH default pack is applied by callers/pipeline; validation accepts resolved non-empty values.
  • Reuse specify_cli.doctrine.sources.git_source.GitSource for clones into temp dirs.

Parallel Opportunities

  • T003 fixtures can be drafted alongside T001/T002 once the package path exists.

Dependencies

  • None.

Risks & Mitigations

  • SSH git@ vs @branch ambiguity → prefer #ref encoding; document @ref only for https/ssh:// URLs (research.md).

Work Package WP02: Ignore-Copy, Substitute & Pipeline (Priority: P0)

Goal: Copy full template trees honouring .templateignore (plus built-in excludes), substitute tokens, fail on leftovers, and expose one pipeline entrypoint. Independent Test: Unit tests prove ignored paths absent, tokens replaced, leftover tokens fail, and pipeline rolls back/cleans temp on failure. Prompt: /tasks/WP02-ignore-copy-and-substitute.md Requirement Refs: FR-007, FR-008, FR-009, FR-010, C-003, NFR-003

Included Subtasks

  • ✅ T006 RED: .templateignore + built-in exclude copy tests
  • ✅ T007 Implement ignore matcher + full-tree copy
  • ✅ T008 [P] RED: token substitute + leftover-token tests
  • ✅ T009 Implement substitute walk + leftover assert
  • ✅ T010 Orchestrate validate→resolve→copy→substitute pipeline

Implementation Notes

  • Add ignore_copy.py and substitute.py; pipeline function in __init__.py or pipeline.py.
  • Built-in excludes: .git/, .templateignore.
  • UTF-8 text substitute; undecodable files left unchanged (research.md).
  • Depends on WP01 types/validators/resolve.

Parallel Opportunities

  • T008 can proceed once destination fixtures exist independently of T006.

Dependencies

  • Depends on WP01.

Risks & Mitigations

  • Partial PACK_PATH on failure → prefer temp staging then move when destination did not exist.

Work Package WP03: CLI Wiring & Compatibility (Priority: P1) 🎯 MVP operator surface

Goal: Extend spec-kitty doctrine org init with template options while preserving minimal-scaffold behaviour and existing CliRunner tests. Independent Test: CliRunner covers no-template scaffold, template local render happy path, invalid ORG_NAME, overwrite guard, and existing validate fixtures still pass. Prompt: /tasks/WP03-cli-wiring.md Requirement Refs: FR-001, FR-002, NFR-001, NFR-002

Included Subtasks

  • ✅ T011 RED: CliRunner template-path + minimal-scaffold regression
  • ✅ T012 Wire --template / --org-name / --local-path / --branch on org_init
  • ✅ T013 Error surfacing (NFR-001) + success output for render path

Implementation Notes

  • Keep org_init thin: build RenderRequest, call pipeline, print errors with rule_id.
  • Do not require --org-name when --template omitted.
  • Extend tests/cli/test_doctrine_org_commands.py without weakening existing cases.

Parallel Opportunities

  • None (single CLI surface).

Dependencies

  • Depends on WP02.

Risks & Mitigations

  • Accidental behaviour change on minimal path → keep existing assertions green before adding template cases.

Parallelization Notes

  • WP01 then WP02 then WP03 (strict library → pipeline → CLI).
  • Within WP01/WP02, RED test drafting marked [P] can overlap implementation of unrelated helpers once paths exist.

MVP Recommendation

  • WP01 + WP02 deliver the library; WP03 is the operator-visible MVP. Ship all three before PR.