[Extension]: Add Domain Spec Maintenance #5147

Extension ID

domain-spec

Extension Name

Domain Spec Maintenance

Version

0.1.0

Description

Keeps canonical per-domain specs: read before specify/plan, updated after implement

Author

Jina Park

Repository URL

https://github.com/jinaparkdev/spec-kit-domain-spec

Download URL

https://github.com/jinaparkdev/spec-kit-domain-spec/archive/refs/tags/v0.1.0.zip

License

MIT

Homepage (optional)

https://github.com/jinaparkdev/spec-kit-domain-spec

Documentation URL (optional)

https://github.com/jinaparkdev/spec-kit-domain-spec/blob/main/README.md

Changelog URL (optional)

https://github.com/jinaparkdev/spec-kit-domain-spec/blob/main/CHANGELOG.md

Required Spec Kit Version

=0.8.5

Required Tools (optional)

- git - optional (implementation diff for the update command)
- rg (ripgrep) - optional (binary-safe code search; falls back to grep -rna)

Number of Commands

3

Number of Hooks (optional)

3

Tags

documentation, governance, specs, living-docs

Key Features

• Keeps one canonical, current-state spec per domain under specs/_domains/<domain>/ (spec.md, data-model.md, contracts/, history.md); feature specs stay as change history
• before_specify / before_plan hooks load the domains a feature touches, so specs and plans are written against today's rules, and record an "Affected Domains" section in the feature spec
• after_implement hook folds the implementation diff back into the touched domain specs, with the code as the source of truth; superseded rules move to a "Retired Rules" table, and spec/code gaps are recorded under "Needs Confirmation"
• Gate: reports an Important issue if a consolidated domain's behaviour changed but its spec was not updated
• Shared rules (auth, paging, ID formats, …) live once under _common/ and are linked, not restated
• bootstrap command scaffolds the directory, proposes a domain map from existing feature specs and code, waits for approval, then writes the first canonical specs
• Configurable output language, feature directory pattern (sequential or issue keys), rule tags, shared-rule domains, data sources, protected paths, search tool and section labels

Testing Checklist

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details

Tested on:

• macOS with Spec Kit 1.2.2, Claude Code and GitHub Copilot integrations

Test projects:

• A sample project (library lending app: three feature specs, Python code, SQL migrations) with planted spec/code mismatches
• A copy of a production repository that already maintained domain specs with an earlier, project-specific version of these commands (Korean labels, issue-key feature directories)

Test scenarios:

1. Installed via --dev and via the v0.1.0 release archive with --from; confirmed the three commands are registered as skills, the three hooks are added to .specify/extensions.yml, and the config template is scaffolded. Reinstalled with --force and confirmed the user config is preserved.
2. bootstrap: scaffolded specs/_domains/, proposed a domain map and stopped for approval; after approval wrote three domains. It caught both planted issues (a page size that differs between spec and code, and a rule retired by a later feature).
3. update after implementing a new feature: added the new rules, resolved the "Needs Confirmation" rows the feature fixed, updated the data model, API contract, history and index.
4. context before specify on both projects: selected the right domains (including shared-rule domains), reported current rules by ID, and wrote no files.

Example Usage

```bash
# Install extension
specify extension add domain-spec --from https://github.com/jinaparkdev/spec-kit-domain-spec/archive/refs/tags/v0.1.0.zip

# Scaffold specs/_domains/ and propose domains from existing feature specs
/speckit-domain-spec-bootstrap

# From then on the hooks run automatically:
#   /speckit-specify, /speckit-plan -> speckit.domain-spec.context
#   /speckit-implement              -> speckit.domain-spec.update

# Run update manually after changes that bypass /speckit-implement (e.g. bug fixes)
/speckit-domain-spec-update specs/014-overdue-fees
```

Proposed Catalog Entry

{
  "domain-spec": {
    "name": "Domain Spec Maintenance",
    "id": "domain-spec",
    "description": "Keeps canonical per-domain specs: read before specify/plan, updated after implement",
    "author": "Jina Park",
    "version": "0.1.0",
    "download_url": "https://github.com/jinaparkdev/spec-kit-domain-spec/archive/refs/tags/v0.1.0.zip",
    "repository": "https://github.com/jinaparkdev/spec-kit-domain-spec",
    "homepage": "https://github.com/jinaparkdev/spec-kit-domain-spec",
    "documentation": "https://github.com/jinaparkdev/spec-kit-domain-spec/blob/main/README.md",
    "changelog": "https://github.com/jinaparkdev/spec-kit-domain-spec/blob/main/CHANGELOG.md",
    "license": "MIT",
    "category": "docs",
    "effect": "read-write",
    "requires": {
      "speckit_version": ">=0.8.5"
    },
    "provides": {
      "commands": 3,
      "hooks": 3
    },
    "tags": ["documentation", "governance", "specs", "living-docs"],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "2026-10-28T00:00:00Z",
    "updated_at": "2026-10-28T00:00:00Z"
  }
}

Additional Context

Related to archive (stn1slv/spec-kit-archive), which merges features into a single memory file after merge. This extension differs in that it keeps one spec per domain plus shared _common/ rules, runs automatically in both directions through hooks (read before specify/plan, write after implement), and keeps a fixed per-domain structure with history and retired rules.