plan-v2-extract-domain

Files (1)

• SKILL.md

SKILL.md (first lines)

Please deep think / ultrathink as this is a complex task.

# extract-domain

Collaboratively identify and formalize an existing codebase concept as a **named domain** without moving files. This is a workshop with the user, not an automated refactor. The goal is **communication** — future plans can reference "the auth domain" and everyone knows what that means.

```md
User input:

$ARGUMENTS
# Expected:
# <concept>                    — the concept to extract (e.g., "authentication", "billing")
# Optional flags:
# --domain <slug>              — override the auto-generated slug
# --list                       — list existing domains and exit
```

## What This Command Does

1. **Explores** the codebase to discover all code related to the concept
2. **Catalogues** discovered files and their roles — presented to user for review
3. **Workshops** with user to define what belongs vs. doesn't (boundary)
4. **Identifies** public interfaces other code already consumes (contracts)
5. **Maps** internal components (services, adapters, repos — composition)
6. **Writes** `docs/domains/<slug>/domain.md` pointing to files where they currently live
7. **Updates** `docs/domains/registry.md` (creates it if first domain)

## What This Command Does NOT Do

- ❌ Move files to a new directory structure
- ❌ Refactor imports
- ❌ Create new source directories
- ❌ Change any code

---

## Step 0: List Mode

If `--list` flag provided:
- Read `docs/domains/registry.md` (if exists)
- Display all registered domains with slug, type, status
- If `docs/domains/domain-map.md` exists, show it too — the map gives the visual overview of how domains relate
- If no registry exists, report "No domains registered yet"
- Exit

## Step 1: Check for Existing Domain

- Read `docs/domains/registry.md` if it exists
- Read `docs/domains/domain-map.md` if it exists — understand the current domain topology, existing contract relationships, and where a new domain might fit
- Check if a domain with matching slug already exists
- If exists: report it and ask user whether to update or abort
- Generate slug from concept: lowercase, replace spaces with hyphens, strip non-alphanumeric

## Step 2: Explore

Launch 2 research subagents in parallel to discover code related to the concept:

**Subagent 1: Code Discovery**
"Find all code related to the concept '<concept>' in this codebase.

Search for:
- Services, handlers, controllers related to <concept>
- Adapters wrapping external SDKs/APIs for <concept>
- Repositories/data access for <concept>
- Models, types, interfaces for <concept>
- Configuration files for <concept>
- Middleware, hooks, plugins for <concept>
- Tests related to <concept>

Output: List of files with suspected roles (service, adapter, repository, model, config, test, middleware, other)"

**Subagent 2: Dependency & Contract Discovery**
"Find how other parts of the codebase consume '<concept>' functionality.

Search for:
- Imports/requires from <concept>-related files
- Public interfaces/classes that other modules depend on
- Event channels, message queues related to <concept>
- Shared types/contracts consumed externally

Output: List of public interfaces with their consumers"

## Step 3: Present & Workshop

Present discovered files to the user in a table:

```
I found these files related to "<concept>":

| # | File | Suspected Role | Include? |
|---|------|---------------|----------|
| 1 | src/services/auth-service.ts | Service | ✅ |
| 2 | src/middleware/jwt.ts | Middleware | ? |
| 3 | src/models/user.ts | Model (shared?) | ? |
| ... | ... | ... | ... |
```

Ask the user to confirm/adjust using the ask_user tool:

1. **For uncertain files**: "Should `<file>` be part of the `<concept>` domain, or does it belong elsewhere?"
2. **Boundary definition**: "What does this domain OWN vs. what does it NOT own?"
3. **Shared files**: "Some files serve multiple concepts. Should I note them as shared?"
4. **Contracts**: "These interfaces are consumed by other code — are they the right public surface?"

**Key principle**: The agent proposes, the user decides. Domain boundary identification is a collaborative conversation.

## Step 3.5: Identify Concepts

Group discovered contracts (from Subagent 2) into **named concepts** — consumer-facing capabilities that the domain offers. Each concept groups related contracts into one capability a consumer might search for.

For each concept, identify:
- **Concept name**: A verb phrase describing what consumers can do (e.g., "Subscribe to file changes", "Authenticate a user")
- **Entry point**: The primary contract/function a consumer imports first
- **What it does**: One sentence describing the capability

**Grouping rules**:
- Related contracts that serve one consumer use case = one concept
- A single contract can be its own concept if it's independently useful
- All concepts that a consumer might search for get a row — not limited to a "top 3"

From AI-Substrate/harness-engineering, MIT.

More from AI-Substrate/harness-engineering