Work Packages: Agent Skills Pack

Inputs: Design documents from kitty-specs/055-agent-skills-pack/ Prerequisites: plan.md (required), spec.md (user stories), research.md, data-model.md, quickstart.md PRD Source: prd-spec-kitty-agent-skills-pack-v1.md Target: Spec Kitty 2.0.11+ (2.x line only)

Tests: Included — 90%+ coverage required per constitution.

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

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

Work Package WP01: Canonical Skill Source Layout & Registry (Priority: P0)

Goal: Create the canonical skill source directory under src/doctrine/skills/ and the skill registry that discovers packaged skills from either local dev checkout or installed package. Independent Test: Registry discovers skills from a test directory and returns correct CanonicalSkill objects. Prompt: tasks/WP01-skill-source-layout-and-registry.md Requirement Refs: FR-001, C-004

Included Subtasks

  • ✅ T001 Create src/doctrine/skills/ directory with placeholder structure
  • ✅ T002 Create src/specify_cli/skills/ package with __init__.py
  • ✅ T003 Implement src/specify_cli/skills/registry.py — discover canonical skills
  • ✅ T004 [P] Unit tests for registry in tests/specify_cli/skills/test_registry.py

Implementation Notes

  • Registry must support both local dev path (get_local_repo_root() → src/doctrine/skills/) and installed package path (get_package_asset_root() → doctrine/skills/)
  • Each discovered skill directory must contain a SKILL.md file to be considered valid
  • Return CanonicalSkill dataclass instances with name, paths to all installable files

Parallel Opportunities

  • T004 (tests) can be written in parallel with T003 (implementation)

Dependencies

  • None (foundational package)

Risks & Mitigations

  • Package path discovery may differ between editable install and wheel install → test both via get_package_asset_root() with mocked paths

Work Package WP02: AGENT_SKILL_CONFIG Capability Matrix (Priority: P0)

Goal: Add the framework capability matrix as a configuration constant alongside the existing AGENT_COMMAND_CONFIG. Independent Test: Import AGENT_SKILL_CONFIG and verify all 13 agents have correct installation classes and skill roots. Prompt: tasks/WP02-agent-skill-config.md Requirement Refs: FR-003, C-001

Included Subtasks

  • ✅ T005 Add installation class constants to src/specify_cli/core/config.py
  • ✅ T006 Add AGENT_SKILL_CONFIG dict to src/specify_cli/core/config.py
  • ✅ T007 Export new symbols from src/specify_cli/core/__init__.py
  • ✅ T008 [P] Unit tests for config entries in tests/specify_cli/core/test_skill_config.py

Implementation Notes

  • Must match PRD section 6 capability matrix exactly
  • Three installation classes: shared-root-capable, native-root-required, wrapper-only
  • Every agent in AI_CHOICES must have a corresponding entry in AGENT_SKILL_CONFIG
  • Include antigravity agent (added in 2.x but not in PRD matrix — default to shared-root-capable)

Parallel Opportunities

  • T008 (tests) can proceed in parallel with T005-T007

Dependencies

  • None (independent constants)

Risks & Mitigations

  • Agent list may diverge from AI_CHOICES → test validates 1:1 correspondence

Work Package WP03: ManagedSkillManifest Dataclass & Persistence (Priority: P0)

Goal: Create the dedicated managed-file manifest with dataclasses and JSON persistence for tracking installed skill files. Independent Test: Create, save, load, and query a manifest with test entries; verify round-trip fidelity. Prompt: tasks/WP03-managed-skill-manifest.md Requirement Refs: FR-004, FR-005, C-005

Included Subtasks

  • ✅ T009 Create ManagedFileEntry and ManagedSkillManifest dataclasses in src/specify_cli/skills/manifest.py
  • ✅ T010 Implement JSON persistence (save/load/clear) to .kittify/skills-manifest.json
  • ✅ T011 Implement helper methods (add_entry, remove_entries_for_agent, find_by_skill)
  • ✅ T012 Implement content hash computation utility (SHA-256)
  • ✅ T013 [P] Unit tests for manifest in tests/specify_cli/skills/test_manifest.py

Implementation Notes

  • Manifest schema version starts at 1
  • Use dataclasses with asdict/from_dict for serialization
  • All timestamps in ISO 8601 UTC
  • Content hash format: sha256:<hex_digest>
  • Use specify_cli.core.atomic.atomic_write for safe persistence

Parallel Opportunities

  • T013 (tests) can proceed alongside implementation

Dependencies

  • None (independent data layer)

Risks & Mitigations

  • Concurrent writes during parallel agent runs → use atomic_write for file safety
  • Schema evolution → version field enables future migrations

Work Package WP04: Skill Installer (Priority: P1)

Goal: Implement the installer that copies canonical skills to agent-specific skill roots based on the capability matrix and builds manifest entries. Independent Test: Install skills for test agents into a temp directory; verify correct files in correct roots with correct manifest entries. Prompt: tasks/WP04-skill-installer.md Requirement Refs: FR-002, FR-003, FR-004, FR-008

Included Subtasks

  • ✅ T014 Implement install_skills_for_agent() in src/specify_cli/skills/installer.py
  • ✅ T015 Implement install_all_skills() orchestration across agents
  • ✅ T016 Handle shared-root deduplication (install once to .agents/skills/)
  • ✅ T017 Build manifest entries during installation and return them
  • ✅ T018 [P] Unit tests for installer in tests/specify_cli/skills/test_installer.py

Implementation Notes

  • For shared-root-capable agents, install to .agents/skills/ only (first root in config)
  • For native-root-required agents, install to vendor-specific root
  • For wrapper-only agents, skip skill installation entirely
  • Preserve existing files not managed by the manifest (don't wipe skill root)
  • Copy entire skill directory tree (SKILL.md + references/ + scripts/ + assets/)

Parallel Opportunities

  • T018 (tests) can proceed alongside implementation

Dependencies

  • Depends on WP01 (registry to discover skills), WP02 (config for routing), WP03 (manifest for entries)

Risks & Mitigations

  • Shared root installed multiple times for multiple agents → track "already installed to shared root" flag
  • File permission issues on Windows → use shutil.copy2 for metadata preservation

Work Package WP05: Init Integration (Priority: P1)

Goal: Add skill installation as a step in spec-kitty init, after wrapper generation and before git initialization. Independent Test: Run init in a temp project; verify skills appear in correct roots and manifest exists. Prompt: tasks/WP05-init-integration.md Requirement Refs: FR-002, FR-008, FR-011, NFR-001

Included Subtasks

  • ✅ T019 Add skill installation step to init.py after generate_agent_assets() call
  • ✅ T020 Add StepTracker entries for skill install progress display
  • ✅ T021 Write manifest to .kittify/skills-manifest.json at end of init
  • ✅ T022 Handle template_mode (local vs package) for skill source discovery
  • ✅ T023 [P] Integration test for init with skills in tests/specify_cli/skills/test_init_integration.py

Implementation Notes

  • Insert skill installation inside the per-agent loop at ~line 775 of init.py
  • Use registry to discover skills from local or package source
  • Use installer to copy skills for each agent
  • Accumulate manifest entries across all agents, write once at end
  • Add tracker steps: {agent_key}-skills → "install skill pack"
  • Must NOT break existing wrapper generation (C-003)

Parallel Opportunities

  • T023 (integration test) can proceed after T019-T022 are complete

Dependencies

  • Depends on WP04 (installer module)

Risks & Mitigations

  • Init.py is large (1140 lines) — surgical insertion required
  • Existing tests may break if init behavior changes → run existing test suite first
  • Template mode handling must match existing local/package/remote patterns

Work Package WP06: Skill Verifier (Priority: P1)

Goal: Implement verification and repair for managed skill files by comparing installed state against the manifest and canonical source. Independent Test: Install skills, corrupt one, verify detects drift, repair restores it. Prompt: tasks/WP06-skill-verifier.md Requirement Refs: FR-006, FR-007

Included Subtasks

  • ✅ T024 Implement verify_installed_skills() in src/specify_cli/skills/verifier.py
  • ✅ T025 Implement VerifyResult dataclass with missing/drifted/unmanaged lists
  • ✅ T026 Implement repair_skills() — restore from canonical source
  • ✅ T027 [P] Unit tests for verifier in tests/specify_cli/skills/test_verifier.py

Implementation Notes

  • verify_installed_skills() reads manifest, checks each entry:
  • File exists? → if not, add to missing
  • Content hash matches? → if not, add to drifted with actual hash
  • Scan skill roots for unmanaged files → add to unmanaged
  • repair_skills() uses registry to find canonical source, copies to installed path, updates manifest hash
  • Both functions take project_path: Path as primary argument

Parallel Opportunities

  • T027 (tests) can proceed alongside implementation

Dependencies

  • Depends on WP03 (manifest for reading installed state)

Risks & Mitigations

  • Canonical source may not be available during repair (corrupted install) → raise clear error with reinstall instructions
  • Partial repair failure → use atomic operations per file, report partial results

Work Package WP07: Verify Integration (Priority: P2)

Goal: Wire skill verification into the existing spec-kitty verify command output. Independent Test: Run spec-kitty verify on a project with skills; see skill status in output. Prompt: tasks/WP07-verify-integration.md Requirement Refs: FR-006, FR-012

Included Subtasks

  • ✅ T028 Add managed skill checks to src/specify_cli/verify_enhanced.py
  • ✅ T029 Display skill verification results with Rich formatting
  • ✅ T030 Detect duplicate skill names across roots
  • ✅ T031 [P] Integration test for verify with skills in tests/specify_cli/skills/test_verify_integration.py

Implementation Notes

  • Read the existing verify_enhanced.py to understand its output pattern
  • Add a new section "Managed Skills" to the verify output
  • Show: total installed, missing, drifted, unmanaged counts
  • If drift detected, show per-file details
  • Duplicate detection: scan all skill roots for duplicate SKILL.md name: values

Parallel Opportunities

  • T031 (integration test) can proceed after T028-T030

Dependencies

  • Depends on WP06 (verifier module)

Risks & Mitigations

  • verify_enhanced.py may have a specific output contract → match existing formatting patterns

Work Package WP08: Author spec-kitty-setup-doctor Skill (Priority: P1)

Goal: Write the first canonical shipped skill with proper SKILL.md, references, and scripts per PRD section 8. Independent Test: Read SKILL.md; confirm it has valid frontmatter, positive triggers, negative scope, and actionable workflow steps. Prompt: tasks/WP08-setup-doctor-skill.md Requirement Refs: FR-009, FR-010, C-006, C-007

Included Subtasks

  • ✅ T032 Write src/doctrine/skills/spec-kitty-setup-doctor/SKILL.md with frontmatter and workflow
  • ✅ T033 Create src/doctrine/skills/spec-kitty-setup-doctor/references/agent-path-matrix.md
  • ✅ T034 Create src/doctrine/skills/spec-kitty-setup-doctor/references/common-failure-signatures.md
  • ✅ T035 [P] Validate skill content against PRD section 8 and design principles

Implementation Notes

  • Frontmatter: name and description only (PRD principle 9)
  • Description must include positive triggers: "set up Spec Kitty", "skills missing", "next is blocked", "runtime is broken"
  • Description must include negative scope: "generic coding questions with no Spec Kitty context"
  • Body: detect agent surface, verify roots/manifest/wrappers, diagnose failures, direct to next command
  • References: agent path matrix (all 13 agents with roots), common failure signatures
  • No repo-specific absolute paths in any content

Parallel Opportunities

  • T035 (validation) can proceed after T032-T034

Dependencies

  • Depends on WP01 (skill directory structure must exist)

Risks & Mitigations

  • Skill content quality directly affects trigger precision → review against PRD section 7 trigger table

Work Package WP09: End-to-End Integration Tests (Priority: P2)

Goal: Comprehensive integration tests covering the full init → verify → repair lifecycle with multiple agent types. Independent Test: All integration tests pass with pytest. Prompt: tasks/WP09-integration-tests.md Requirement Refs: NFR-003, NFR-005

Included Subtasks

  • ✅ T036 Test full init → verify → repair cycle in tests/specify_cli/skills/test_e2e.py
  • ✅ T037 Test per-installation-class distribution (shared, native, wrapper-only)
  • ✅ T038 Test manifest persistence across sessions (save, reload, query)
  • ✅ T039 Test drift detection and repair (delete, modify, verify, repair)
  • ✅ T040 Test with multiple agents of different installation classes simultaneously

Implementation Notes

  • Use tmp_path fixture for all filesystem tests
  • Mock get_local_repo_root() and get_package_asset_root() to point to test fixtures
  • Create minimal skill fixtures (single SKILL.md with frontmatter)
  • Test all three installation classes in same test to verify shared-root deduplication
  • Verify manifest JSON structure matches schema

Parallel Opportunities

  • Individual test functions are independent

Dependencies

  • Depends on WP05 (init integration), WP07 (verify integration), WP08 (skill content)

Risks & Mitigations

  • Tests may be slow if they invoke full init → use focused integration tests that call installer/verifier directly
  • Flaky tests from filesystem timing → use synchronous operations only

Work Package WP10: Packaging Completeness (Priority: P1)

Goal: Resolved: packages = ["src/specify_cli"] in hatch config auto-includes all subpackages including skills/. The also_copy entry was added to [tool.mutmut] for mutation testing environment consistency, not for wheel packaging. Independent Test: Verify the skills module would be included in a wheel build. Prompt: tasks/WP10-packaging-completeness.md Requirement Refs: NFR-005

Included Subtasks

  • ✅ T041 Add src/specify_cli/skills/ to also_copy in pyproject.toml
  • ✅ T042 [P] Add packaging verification test confirming skills module is discoverable

Dependencies

  • Depends on WP01-WP09 (first slice complete)

Work Package WP11: Author spec-kitty-runtime-next Skill (Priority: P1)

Goal: Author the second canonical shipped skill that teaches agents the spec-kitty next --agent <name> control loop (PRD section 8). Independent Test: Install via registry, verify correct frontmatter, triggers, workflow steps, and that it installs alongside setup-doctor without conflicts. Prompt: tasks/WP11-runtime-next-skill.md Requirement Refs: FR-009, FR-010, C-006, C-007

Included Subtasks

  • ✅ T043 Write src/doctrine/skills/spec-kitty-runtime-next/SKILL.md with frontmatter and workflow
  • ✅ T044 Create src/doctrine/skills/spec-kitty-runtime-next/references/runtime-result-taxonomy.md
  • ✅ T045 Create src/doctrine/skills/spec-kitty-runtime-next/references/blocked-state-recovery.md
  • ✅ T046 [P] Test registry discovers both skills and installer handles multi-skill pack

Dependencies

  • Depends on WP10 (packaging complete)

Work Package WP12: Author spec-kitty-orchestrator-api-operator Skill (Priority: P2)

Goal: Author the canonical orchestrator-api skill teaching external systems how to use the orchestrator-api contract correctly (PRD section 8). Independent Test: Registry discovers the skill; content references only real orchestrator-api commands. Prompt: tasks/WP12-orchestrator-api-operator-skill.md Requirement Refs: FR-009, FR-010, C-006, C-007

Included Subtasks

  • ✅ T047 Write src/doctrine/skills/spec-kitty-orchestrator-api-operator/SKILL.md
  • ✅ T048 Create references/orchestrator-api-contract.md
  • ✅ T049 Create references/host-boundary-rules.md

Dependencies

  • Depends on WP01 (skill directory structure)

Scope Decision: spec-kitty-specify-plan and spec-kitty-mission-orchestrator

Decision: Do NOT author these two skills per architectural boundary review.

  • spec-kitty-specify-plan teaches _how to do product work_ (discovery, spec writing, planning), not _how to use Spec Kitty_. The specify/plan behavior is owned by the mission state machine and spec-kitty next. A skill here would duplicate mission composition logic.
  • spec-kitty-mission-orchestrator is mission composition — deciding when to delegate to setup, doctrine, runtime, or review. That sequencing belongs in the mission state machine and future doctrine mission compiler (Issue #327), not in a hand-authored skill.

Both were called out in the PRD section 7 but the architectural boundary review (PR #305 / Issue #327 context) correctly identifies them as mission-authoring territory, not product-operation territory.

6 skills shipped. 2 skills deferred to doctrine mission compiler.

Dependency & Execution Summary

Phase 0 (parallel, no dependencies):
  WP01 (registry) ──┐
  WP02 (config)   ──┼──> WP04 (installer) ──> WP05 (init integration)
  WP03 (manifest) ──┤                                    │
                     └──> WP06 (verifier) ──> WP07 (verify integration) ──┐
                     │                                                     ├──> WP09 (e2e tests)
  WP01 ──────────────└──> WP08 (setup-doctor skill) ─────────────────────┘

Parallel waves:

  • Wave 1: WP01, WP02, WP03 (all independent)
  • Wave 2: WP04, WP06, WP08 (WP04 needs Wave 1; WP06 needs WP03; WP08 needs WP01)
  • Wave 3: WP05, WP07 (WP05 needs WP04; WP07 needs WP06)
  • Wave 4: WP09 (needs WP05, WP07, WP08)

MVP Scope: WP01-WP05 + WP08 deliver a working init with skills. WP06-WP07 add verify. WP09 adds confidence.

Requirements Coverage Summary

Requirement IDCovered By Work Package(s)
FR-001WP01
FR-002WP04, WP05
FR-003WP02, WP04
FR-004WP03, WP04
FR-005WP03
FR-006WP06, WP07
FR-007WP06
FR-008WP04, WP05
FR-009WP08
FR-011WP05
FR-010WP08
FR-012WP07
NFR-001WP05
NFR-003WP09
NFR-005WP09
C-001WP02
C-004WP01
C-005WP03
C-006WP08
C-007WP08

Subtask Index (Reference)

Subtask IDSummaryWork PackagePriorityParallel?
T001Create doctrine/skills/ directoryWP01P0No
T002Create specify_cli/skills/ packageWP01P0No
T003Implement registry.pyWP01P0No
T004Unit tests for registryWP01P0Yes
T005Add installation class constantsWP02P0No
T006Add AGENT_SKILL_CONFIG dictWP02P0No
T007Export new symbolsWP02P0No
T008Unit tests for configWP02P0Yes
T009Create manifest dataclassesWP03P0No
T010Implement JSON persistenceWP03P0No
T011Implement helper methodsWP03P0No
T012Content hash utilityWP03P0No
T013Unit tests for manifestWP03P0Yes
T014Implement install_skills_for_agentWP04P1No
T015Implement install_all_skillsWP04P1No
T016Shared-root deduplicationWP04P1No
T017Build manifest entriesWP04P1No
T018Unit tests for installerWP04P1Yes
T019Add skill install to init.pyWP05P1No
T020Add StepTracker entriesWP05P1No
T021Write manifest at end of initWP05P1No
T022Handle template_mode for skillsWP05P1No
T023Integration test for initWP05P1Yes
T024Implement verify_installed_skillsWP06P1No
T025Implement VerifyResult dataclassWP06P1No
T026Implement repair_skillsWP06P1No
T027Unit tests for verifierWP06P1Yes
T028Add skill checks to verify_enhancedWP07P2No
T029Display results with RichWP07P2No
T030Detect duplicate skill namesWP07P2No
T031Integration test for verifyWP07P2Yes
T032Write SKILL.md for setup-doctorWP08P1No
T033Create agent-path-matrix referenceWP08P1No
T034Create failure-signatures referenceWP08P1No
T035Validate skill contentWP08P1Yes
T036Test full init→verify→repair cycleWP09P2No
T037Test per-class distributionWP09P2Yes
T038Test manifest persistenceWP09P2Yes
T039Test drift detection and repairWP09P2Yes
T040Test multiple agents simultaneouslyWP09P2Yes