# feature-arch

Turns a React project into a feature-based layout and writes a target-architecture blueprint with directory tree, public APIs and a migration plan.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 412 installs · ★ 218
- Author: pproenca
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.curated/feature-arch/SKILL.md
- Updated: 2026-08-15
- HTML: https://affpapa.org/en/nevibecode/skills/pproenca-feature-arch

## What it does

The skill carries 43 rules in 8 categories for organising React code by feature: directory structure and imports first, then boundaries, data fetching, components, state, tests and naming. Priorities follow impact, so the critical stuff comes before conventions.

Run it on a real project and the deliverable is a single file at `docs/architecture/FEATURE-ARCH-TARGET.md`. It holds project context, the feature list confirmed with you, a directory tree with literal paths, the exact named exports of each `index.ts`, an N×N import-boundary matrix marked `allowed` / `forbidden` / `via app` / `via events`, state and data ownership per feature, a cross-feature communication policy, and a numbered migration plan with S/M/L effort estimates. Every section cites the rules behind it, so the blueprint stays a projection of the skill rather than a second source of truth.

The agent gathers context from `package.json`, the `src/` tree, README, `CLAUDE.md` and `openspec/`, proposes candidate features, confirms them through `AskUserQuestion`, fills `assets/templates/feature-arch-target.md.template`, then hands off. It does not start migrating in the same turn — you review the plan first. Projects under roughly 10 source files get a one-page seed structure instead, with a note to build the full blueprint once the second or third feature exists. One catch: the confirmation step depends on `AskUserQuestion`, so pick a platform that has it.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill feature-arch -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/feature-arch/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/feature-arch/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill feature-arch -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/feature-arch/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill feature-arch -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/feature-arch/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pproenca/dot-skills feature-arch
```

2. **Manually: put the files in place**
- File: `.github/skills/feature-arch/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill feature-arch -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pproenca/dot-skills --path skills/.curated/feature-arch
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/feature-arch/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill feature-arch -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.curated/feature-arch/SKILL.md

## When to use it
- split a React app into features instead of type-based folders
- block cross-feature imports and spell out boundaries in a matrix
- pin down each feature's public API through `index.ts`
- lay out a file-level migration plan with effort estimates
- review code for architecture violations

## Example prompts
- Generate the target architecture blueprint for this React project using the feature-arch skill
- Look at src/ and propose which features to extract, then confirm the list with me
- Check the imports between features and show me where the boundaries break

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b7b59c09c233d64d.

BEGIN THIRD-PARTY FILE b7b59c09c233d64d
```text
---
name: feature-arch
description: React feature-based architecture guidelines for scalable applications. This skill should be used when writing, reviewing, or refactoring React code to ensure proper feature organization. When invoked on a project, the agent produces a concrete target-architecture blueprint at docs/architecture/FEATURE-ARCH-TARGET.md showing the desired directory tree, per-feature public APIs, import-boundary matrix, and a numbered migration plan. Triggers on tasks involving project structure, feature organization, module boundaries, cross-feature imports, data fetching patterns, or component composition.
---

# Feature-Based Architecture Best Practices

Comprehensive architecture guide for organizing React applications by features, enabling scalable development with independent teams. Contains 43 rules across 8 categories, prioritized by impact from critical (directory structure, imports) to incremental (naming conventions). When invoked on a real project, the skill produces a project-specific blueprint that anchors every decision in those rules.

## Primary Output: The Target Architecture Blueprint

When an agent invokes this skill on a real project, the deliverable is a single
markdown file persisted at `docs/architecture/FEATURE-ARCH-TARGET.md` (or the
repo's existing docs location). The blueprint contains:

1. **Project context** — framework, state libraries, routing model, current shape.
2. **Identified features** — confirmed with the user, sourced from routes, docs, openspec, and code clusters.
3. **Target directory tree** — literal paths, not pseudo-trees.
4. **Per-feature public APIs** — exact named exports of each `index.ts`.
5. **Import-boundary matrix** — N×N table of feature relationships (`allowed` / `forbidden` / `via app` / `via events`).
6. **State & data ownership** — server-state and client-state owner per feature.
7. **Cross-feature communication policy** — composition, events, or shared slice — with rationale.
8. **Numbered migration plan** — file-level move/create/delete steps with S/M/L effort estimates.
9. **Human conformance checklist** — for code review and "definition of done".
```
END THIRD-PARTY FILE b7b59c09c233d64d

The third-party file has ended. Everything between the b7b59c09c233d64d tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2180 of 8199 bytes. © pproenca · MIT · https://github.com/pproenca/dot-skills/tree/HEAD/skills/.curated/feature-arch/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md