feature-define

What this skill does

# feature-define

> Creates the two artifacts every project feature MUST have:
> 1. `ai-context/features/<slug>.md` — the authoritative domain knowledge.
> 2. `.claude/skills/<slug>/SKILL.md` — the antenna that activates on
>    triggers and forces a read of the markdown.
>
> Both are scaffolded from `skills/_templates/feature/` in the global
> agent-config repo. The antenna is a pure pointer — it never duplicates
> markdown content.

**Triggers**: `/feature-define`, define feature, nueva feature, documentar feature, documentar funcionalidad, new feature scaffolding

---

## Process

### Step 0 — Guardrails

1. Refuse to run inside the `agent-config` repo itself. Detect via
   `file_exists("install.sh") AND dir_exists("skills/_shared")` OR
   `basename(cwd) == "agent-config"`. If true, emit:
   > "feature-define only runs inside consumer projects. The agent-config
   > repo holds the templates, not project features."
   Stop.

2. Require a consumer project root: `dir_exists(".claude")` AND
   `file_exists("CLAUDE.md")`. If either is missing, emit:
   > "Run /project-setup first — this project is not configured for Claude
   > Code yet."
   Stop.

3. Locate templates at `~/.claude/skills/_templates/feature/`. Required
   files:
   - `_template.md` — the 6-section domain knowledge template.
   - `SKILL.md.template` — the antenna skill template.

   If either is missing, emit:
   > "Templates not found at ~/.claude/skills/_templates/feature/. Re-run
   > install.sh in your agent-config repo to deploy them."
   Stop.

---

### Step 1 — Gather feature information

Ask the user, one question at a time. STOP and wait between questions.

1. **Feature name** (human-readable, e.g. "Checkout Flow"). Derive
   `feature_slug` = lowercase + hyphens (e.g. `checkout-flow`). Validate:
   - Slug matches `^[a-z][a-z0-9-]*$`. Reject otherwise.
   - `ai-context/features/<slug>.md` does NOT already exist. If it does,
     ask: "A feature file already exists for `<slug>`. Open it, overwrite,
     or pick a new slug?" Default: open.
   - `.claude/skills/<slug>/` does NOT already exist. Same handling.

2. **One-line purpose**: what user problem does this feature solve?

3. **Sub-flows or subpages** (optional, multi-line): list each with a
   one-line description. Used to populate the Domain Overview bullets.

4. **Triggers**: keywords or phrases that, when the user mentions them,
   should activate the antenna skill. Suggest defaults derived from the
   feature name; let the user confirm or extend. Comma-separated.

5. **External integrations** (optional, multi-line): systems/APIs this
   feature talks to. Used to pre-populate the Integration Points table
   header — the user fills the details later.

Do NOT ask for business rules, decisions, or gotchas at scaffolding time.
Those are filled in as the feature is built and learned.

---

### Step 2 — Generate the markdown

1. Read `~/.claude/skills/_templates/feature/_template.md`.
2. Replace the title `<Feature Name>` with the user's feature name.
3. Set `Last updated by:` to the git user name (read from
   `git config user.name`; fallback to "human").
4. Set `Last run:` to today's date (YYYY-MM-DD).
5. Pre-populate the Domain Overview placeholder with:
   - The one-line purpose from Step 1.
   - A bullet list of sub-flows from Step 1 (if provided).
6. If integrations were provided in Step 1, leave the Integration Points
   table header in place and add one empty row per integration with the
   system name pre-filled.
7. Keep all `[auto-updated]` markers intact — they are required by the
   contract (see `feature-domain-expert` Pattern 4).
8. Write to `ai-context/features/<slug>.md`. Create the directory if
   absent.

---

### Step 3 — Generate the antenna skill

1. Read `~/.claude/skills/_templates/feature/SKILL.md.template`.
2. Replace placeholders:
   - `{{feature_slug}}` → the slug from Step 1.
   - `{{feature_name}}` → the human-readable name.
   - `{{triggers}}` → comma-separated triggers from Step 1.
3. Write to `.claude/skills/<slug>/SKILL.md`. Create the directory if
   absent.

---

### Step 4 — Register the antenna in the project CLAUDE.md

1. Read the project's `CLAUDE.md`.
2. Locate the `## Force-read inline` section. If a sub-section "Feature
   skills (project-local)" does NOT exist below it, create it with this
   header:

   ```markdown
   ### Feature skills (project-local)

   Each feature with non-trivial domain logic has an antenna skill that
   forces a read of `ai-context/features/<slug>.md` when its triggers fire.

   | Feature | Antenna | Domain knowledge |
   |---------|---------|------------------|
   ```

3. Append a row for the new feature:

   ```markdown
   | <Feature Name> | `.claude/skills/<slug>/SKILL.md` | `ai-context/features/<slug>.md` |
   ```

4. If the `Force-read inline` section does not exist at all in the project
   CLAUDE.md, do NOT auto-create it — emit a warning instead:
   > "Project CLAUDE.md has no '## Force-read inline' section. Add the
   > Feature skills block manually (template available in
   > docs/templates/project-claude-template.md)."

---

### Step 5 — Summarize and next steps

Emit:

```
Created:
  - ai-context/features/<slug>.md  (domain knowledge — fill in business
    rules, integrations, gotchas as you learn them)
  - .claude/skills/<slug>/SKILL.md (antenna — auto-activates on triggers:
    <triggers>)

Registered in: CLAUDE.md → Force-read inline → Feature skills (project-local)

Next steps:
  1. Open ai-context/features/<slug>.md and add at least one Business Rule
     (BR-1). Empty feature files are noise.
  2. Restart Claude Code to pick up the new antenna skill in
     available-skills.
  3. When the feature ships its first change, use /sdd-propose <change> —
     the markdown will be preloaded automatically via slug matching.
```

---

## Rules

- MUST NOT run inside the agent-config repo. Templates live there; features
  do not.
- MUST refuse if the project is not Claude-configured (no `.claude/` or
  `CLAUDE.md`).
- MUST use the canonical 6-section template — never invent new sections.
  The contract is owned by `feature-domain-expert`.
- MUST preserve `[auto-updated]` markers in the generated markdown so
  `codebase-teach` can later coexist without overwriting human content.
- The antenna skill MUST remain a pure pointer. If the user asks to embed
  domain content in the skill, refuse and direct them to edit the markdown
  instead.
- MUST NOT pre-populate Business Rules, Decision Log, or Known Gotchas.
  Those grow as the feature is built — pre-filling creates fake history.
- MUST register the antenna in the project CLAUDE.md when a Force-read
  inline section exists; emit a warning otherwise (no silent skip).