fearovex/feature-define

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:

   ### 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:

   | <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).