@ax-skills/react-development 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTENT-LICENSE +40 -0
- package/LICENSE +21 -0
- package/README.md +42 -2
- package/bin/install.mjs +59 -0
- package/package.json +39 -4
- package/skills/ax-react-architecture/SKILL.md +67 -0
package/CONTENT-LICENSE
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
Creative Commons Attribution 4.0 International (CC BY 4.0)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aaron Peloquin
|
|
4
|
+
|
|
5
|
+
Scope of This License:
|
|
6
|
+
This license applies to all written articles, documentation, architecture diagrams,
|
|
7
|
+
and agent skill definitions in this repository, specifically:
|
|
8
|
+
|
|
9
|
+
- content/articles/**
|
|
10
|
+
- .agents/skills/**
|
|
11
|
+
|
|
12
|
+
Exclusions:
|
|
13
|
+
|
|
14
|
+
- Application source code, configuration, and tooling (`src/**`, `eslint/**`,
|
|
15
|
+
and root config files) are licensed separately under the MIT License (`./LICENSE`).
|
|
16
|
+
- Custom brand marks (`public/logo.svg`, `public/favicon.svg`, `public/logo-badge.svg`)
|
|
17
|
+
are reserved brand assets (All Rights Reserved) and are not granted under CC BY 4.0.
|
|
18
|
+
|
|
19
|
+
You are free to:
|
|
20
|
+
|
|
21
|
+
- Share — copy and redistribute the material in any medium or format for any purpose,
|
|
22
|
+
even commercially.
|
|
23
|
+
- Adapt — remix, transform, and build upon the material for any purpose, even commercially.
|
|
24
|
+
|
|
25
|
+
Under the following terms:
|
|
26
|
+
|
|
27
|
+
- Attribution — You must give appropriate credit, provide a link to the license, and
|
|
28
|
+
indicate if changes were made. You may do so in any reasonable manner (including a
|
|
29
|
+
single-line slide-footer credit such as:
|
|
30
|
+
"Source: Aaron Peloquin, Agent Experience (AX) - agent-experience.ai (CC BY 4.0)"),
|
|
31
|
+
but not in any way that suggests the licensor endorses you or your use.
|
|
32
|
+
- No additional restrictions — You may not apply legal terms or technological measures
|
|
33
|
+
that legally restrict others from doing anything the license permits.
|
|
34
|
+
|
|
35
|
+
No Warranties:
|
|
36
|
+
This material is provided "as-is" without warranty of any kind, as set forth in Section 5
|
|
37
|
+
of the CC BY 4.0 Legal Code.
|
|
38
|
+
|
|
39
|
+
Full Legal Code:
|
|
40
|
+
<https://creativecommons.org/licenses/by/4.0/legalcode>
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aaron Peloquin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,43 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@ax-skills/react-development`
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Agent Experience (AX) React architecture skill enforcing Prescriptive 5-Tier Atomic Design, custom hook isolation, Provider/Hook splitting, and React Compiler boundaries.
|
|
4
|
+
|
|
5
|
+
**Canonical Documentation:** [https://agent-experience.ai](https://agent-experience.ai)
|
|
6
|
+
|
|
7
|
+
## Quick Install & Patching
|
|
8
|
+
|
|
9
|
+
Run the package directly from your project root to install or update (patch) the bundled `SKILL.md` directories into `.agents/skills/`:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
# Install or update using pnpm
|
|
13
|
+
pnpm dlx @ax-skills/react-development@latest
|
|
14
|
+
|
|
15
|
+
# Or using npx
|
|
16
|
+
npx @ax-skills/react-development@latest
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
### Custom Target Directory
|
|
20
|
+
|
|
21
|
+
By default, skills are written to `.agents/skills/<skill-name>/SKILL.md`. Pass `--target <dir>` to install into another agent skill directory (such as `.claude/skills` or `.cursor/skills`):
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pnpm dlx @ax-skills/react-development@latest --target .claude/skills
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Included Skills
|
|
28
|
+
|
|
29
|
+
| Skill ID | Documentation Article | Summary |
|
|
30
|
+
| :--- | :--- | :--- |
|
|
31
|
+
| `ax-react-architecture` | [React Architecture Standards](https://agent-experience.ai/articles/ax/skills/react-architecture) | Enforces Prescriptive 5-Tier Atomic Design, custom hook extraction, Provider/Hook isolation, and React Compiler + ESLint boundary rules. |
|
|
32
|
+
|
|
33
|
+
## Available `@ax-skills` Packages
|
|
34
|
+
|
|
35
|
+
* `@ax-skills/workflow` — 4 Software Factory workflow skills (`ax-specification-sharpening`, `ax-ticket-tree`, `ax-proof-pass`, `ax-interface-iteration`)
|
|
36
|
+
* `@ax-skills/software-development` — Core software engineering standards (`ax-software-engineering`)
|
|
37
|
+
* `@ax-skills/react-development` — React & Atomic Design architecture standards (`ax-react-architecture`)
|
|
38
|
+
* `@ax-skills/all` — All 6 public Agent Experience (AX) skills in a single bundle
|
|
39
|
+
|
|
40
|
+
## License
|
|
41
|
+
|
|
42
|
+
* **Skill documents (`skills/**/SKILL.md`):** [Creative Commons Attribution 4.0 International (CC BY 4.0)](./CONTENT-LICENSE)
|
|
43
|
+
* **Installer script (`bin/install.mjs`):** [MIT License](./LICENSE)
|
package/bin/install.mjs
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import fs from "node:fs";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
import { fileURLToPath } from "node:url";
|
|
5
|
+
|
|
6
|
+
function runInstaller() {
|
|
7
|
+
const args = process.argv.slice(2);
|
|
8
|
+
let targetRelDir = ".agents/skills";
|
|
9
|
+
|
|
10
|
+
for (let i = 0; i < args.length; i += 1) {
|
|
11
|
+
const arg = args[i];
|
|
12
|
+
if (arg === "--target" || arg === "-t") {
|
|
13
|
+
const nextArg = args[i + 1];
|
|
14
|
+
if (!nextArg || nextArg.startsWith("-")) {
|
|
15
|
+
console.error(
|
|
16
|
+
"What failed: CLI argument parsing. Why: --target requires a directory path. Fix: Pass a relative path such as --target .agents/skills"
|
|
17
|
+
);
|
|
18
|
+
process.exit(1);
|
|
19
|
+
}
|
|
20
|
+
targetRelDir = nextArg;
|
|
21
|
+
i += 1;
|
|
22
|
+
} else if (arg.startsWith("--target=")) {
|
|
23
|
+
targetRelDir = arg.slice("--target=".length);
|
|
24
|
+
} else if (arg === "--help" || arg === "-h") {
|
|
25
|
+
console.log("Usage: npx @ax-skills/react-development@latest [--target <dir>]");
|
|
26
|
+
process.exit(0);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
const currentFilePath = fileURLToPath(import.meta.url);
|
|
31
|
+
const packageRoot = path.resolve(path.dirname(currentFilePath), "..");
|
|
32
|
+
const bundledSkillsDir = path.join(packageRoot, "skills");
|
|
33
|
+
const destinationRoot = path.resolve(process.cwd(), targetRelDir);
|
|
34
|
+
|
|
35
|
+
if (!fs.existsSync(bundledSkillsDir)) {
|
|
36
|
+
console.error(
|
|
37
|
+
`What failed: Skill bundle discovery. Why: Missing directory ${bundledSkillsDir}. Fix: Reinstall the package from npm.`
|
|
38
|
+
);
|
|
39
|
+
process.exit(1);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
const entries = fs
|
|
43
|
+
.readdirSync(bundledSkillsDir, { withFileTypes: true })
|
|
44
|
+
.filter((entry) => entry.isDirectory());
|
|
45
|
+
|
|
46
|
+
fs.mkdirSync(destinationRoot, { recursive: true });
|
|
47
|
+
|
|
48
|
+
for (const entry of entries) {
|
|
49
|
+
const srcDir = path.join(bundledSkillsDir, entry.name);
|
|
50
|
+
const destDir = path.join(destinationRoot, entry.name);
|
|
51
|
+
fs.rmSync(destDir, { recursive: true, force: true });
|
|
52
|
+
fs.cpSync(srcDir, destDir, { recursive: true });
|
|
53
|
+
console.log(`[@ax-skills/react-development] Installed ${entry.name} -> ${path.relative(process.cwd(), destDir)}`);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
console.log(`[@ax-skills/react-development@0.1.1] Installed ${entries.length} skill(s) into ${targetRelDir}`);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
runInstaller();
|
package/package.json
CHANGED
|
@@ -1,6 +1,41 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ax-skills/react-development",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "Agent Experience (AX) React architecture skill enforcing Prescriptive 5-Tier Atomic Design, custom hook isolation, Provider/Hook splitting, and React Compiler boundaries.",
|
|
5
|
+
"license": "(MIT AND CC-BY-4.0)",
|
|
6
|
+
"author": "Aaron Peloquin (https://agent-experience.ai)",
|
|
7
|
+
"homepage": "https://agent-experience.ai",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/aaron-peloquin/agent-experience.git"
|
|
11
|
+
},
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/aaron-peloquin/agent-experience/issues"
|
|
14
|
+
},
|
|
15
|
+
"publishConfig": {
|
|
16
|
+
"access": "public"
|
|
17
|
+
},
|
|
18
|
+
"type": "module",
|
|
19
|
+
"bin": {
|
|
20
|
+
"ax-skills-react-development": "bin/install.mjs"
|
|
21
|
+
},
|
|
22
|
+
"files": [
|
|
23
|
+
"skills/",
|
|
24
|
+
"bin/",
|
|
25
|
+
"README.md",
|
|
26
|
+
"LICENSE",
|
|
27
|
+
"CONTENT-LICENSE"
|
|
28
|
+
],
|
|
29
|
+
"keywords": [
|
|
30
|
+
"agent-experience",
|
|
31
|
+
"ax",
|
|
32
|
+
"agent-skills",
|
|
33
|
+
"skills",
|
|
34
|
+
"react",
|
|
35
|
+
"atomic-design",
|
|
36
|
+
"react-compiler"
|
|
37
|
+
],
|
|
38
|
+
"engines": {
|
|
39
|
+
"node": ">=18.0.0"
|
|
40
|
+
}
|
|
41
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ax-react-architecture
|
|
3
|
+
description: Invoke whenever building or refactoring React components, extracting business logic into custom hooks, adding Context providers, organizing UI folders, or configuring React ESLint, TypeScript, and React Compiler tooling.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Skill: React Architecture Standards (`ax-react-architecture`)
|
|
7
|
+
|
|
8
|
+
## Role & Architectural Mandate
|
|
9
|
+
|
|
10
|
+
Act as a Principal Frontend Systems Engineer. Keep React components thin and declarative by moving state transitions and browser side effects into custom hooks, placing every UI module into a 5-tier Atomic Design hierarchy, enabling React Compiler, and enforcing structural invariants through concrete lint and type rules.
|
|
11
|
+
|
|
12
|
+
## Thin Components & Hook Extraction
|
|
13
|
+
|
|
14
|
+
Apply these structural rules across every TypeScript and React module:
|
|
15
|
+
|
|
16
|
+
* **Pure Core Logic (`src/core/`):** Place domain transformations, parsers, and formatters in pure TypeScript modules with zero React or DOM imports.
|
|
17
|
+
* **Custom Hooks (`src/hooks/`):** Extract component state transitions, Context reads, data fetching, and browser side effects (`fetch`, `localStorage`, clipboard, timers) into dedicated hooks.
|
|
18
|
+
* **Declarative Visual Shell (`src/components/`):** Render JSX strictly from props and hook return values. Ban inline data pipelines, regex parsing, and direct browser API calls inside component bodies.
|
|
19
|
+
* **One Function Per File:** Export one component, hook, or helper per file. Extract secondary helpers into `src/core/` or separate Atom and Molecule files.
|
|
20
|
+
* **250-Line Ceiling:** Keep every source file at or below 250 lines including imports, types, and whitespace. Decompose modules once they approach 200 lines.
|
|
21
|
+
* **Three-File Provider Split:** Split every Context Provider across three single-export modules:
|
|
22
|
+
* `src/providers/<domain>/<Name>Context.ts` (Context object and types only)
|
|
23
|
+
* `src/providers/<domain>/<Name>Provider.tsx` (Provider component only)
|
|
24
|
+
* `src/hooks/use<Name>.ts` (Custom consumer hook only)
|
|
25
|
+
|
|
26
|
+
## 5-Tier Atomic Design Boundaries
|
|
27
|
+
|
|
28
|
+
Place every UI file in its exact tier and enforce unidirectional imports from lower tiers upward:
|
|
29
|
+
|
|
30
|
+
| Tier | Directory | Responsibility | Allowed Imports |
|
|
31
|
+
| :--- | :--- | :--- | :--- |
|
|
32
|
+
| **Core** | `src/core/` | Pure TypeScript domain logic with zero React or DOM dependencies. | `core` |
|
|
33
|
+
| **Hooks** | `src/hooks/` | Stateful transitions, browser API side effects, and Context consumers. | `core`, `hooks`, `providers` |
|
|
34
|
+
| **1. Atoms** | `src/components/atoms/` | Wrap a single HTML primitive (`button`, `a`, `input`, `code`) with typed, accessible props. | `core`, `hooks` |
|
|
35
|
+
| **2. Molecules** | `src/components/molecules/` | Compose two or more Atoms into one prop-driven functional unit. | `core`, `hooks`, `atoms` |
|
|
36
|
+
| **3. Organisms** | `src/components/organisms/` | Assemble complex UI regions that may consume shared Context via hooks. | `core`, `hooks`, `atoms`, `molecules`, `providers` |
|
|
37
|
+
| **4. Templates** | `src/components/templates/` | Define stateless page layout skeletons arranging Organisms into responsive grids. | `core`, `hooks`, `atoms`, `molecules`, `organisms`, `providers` |
|
|
38
|
+
| **5. Providers** | `src/providers/` | Manage scoped Context state shared across multiple Organisms. | `core`, `hooks`, `providers` |
|
|
39
|
+
| **App / Routes** | `src/app/` | Wire route data loading, scoped Providers, and page Templates. | `core`, `hooks`, `atoms`, `molecules`, `organisms`, `templates`, `providers` |
|
|
40
|
+
|
|
41
|
+
## React Compiler & Concrete Guardrails
|
|
42
|
+
|
|
43
|
+
Push architectural constraints into deterministic compiler, lint, and type checks rather than relying on prose reminders:
|
|
44
|
+
|
|
45
|
+
* **Enable React Compiler:** Turn on React Compiler in the build configuration (for example, `babel-plugin-react-compiler` or framework options such as `reactCompiler: true`) so the compiler handles memoization automatically across components and hooks.
|
|
46
|
+
* **Enforce Hook & Compiler Lint Rules:** Mount `eslint-plugin-react-hooks` (`reactHooks.configs.flat.recommended`) so `rules-of-hooks`, `exhaustive-deps`, and React Compiler diagnostics fail CI immediately.
|
|
47
|
+
* **Configure Strict ESLint Guardrails:** When setting up or auditing a React repository, install and preserve these off-the-shelf rules in `eslint.config.mjs`:
|
|
48
|
+
* `typescript-eslint` (`strictTypeChecked` with `projectService: true`) for type-aware linting.
|
|
49
|
+
* `eslint-plugin-boundaries` (`boundaries/element-types` with `default: "disallow"`) matching the 5-tier table above.
|
|
50
|
+
* `eslint-plugin-unused-imports` (`no-unused-imports` and `no-unused-vars`) for zero dead code.
|
|
51
|
+
* `max-lines` set to `250` (`skipBlankLines: false`, `skipComments: false`).
|
|
52
|
+
* `no-restricted-syntax` enforcing one top-level function per file via AST selector:
|
|
53
|
+
|
|
54
|
+
```text
|
|
55
|
+
Program > :matches(FunctionDeclaration, ExportNamedDeclaration:has(FunctionDeclaration), ExportDefaultDeclaration:has(FunctionDeclaration), VariableDeclaration:has(ArrowFunctionExpression, FunctionExpression)) ~ :matches(FunctionDeclaration, ExportNamedDeclaration:has(FunctionDeclaration), ExportDefaultDeclaration:has(FunctionDeclaration), VariableDeclaration:has(ArrowFunctionExpression, FunctionExpression))
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
* **Configure Strict TypeScript:** Preserve `strict`, `allowJs: false`, `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noFallthroughCasesInSwitch`, `noUncheckedIndexedAccess`, and `exactOptionalPropertyTypes` in `tsconfig.json`.
|
|
59
|
+
* **Zero Rule Suppressions:** Never weaken or bypass these checks with `eslint-disable`, `@ts-ignore`, or `@ts-expect-error`. Fix the underlying boundary, hook, or type error directly.
|
|
60
|
+
|
|
61
|
+
## Verification Checklist
|
|
62
|
+
|
|
63
|
+
Before finishing any React change, confirm every check passes:
|
|
64
|
+
|
|
65
|
+
* Every visual component stays declarative and delegates state transitions or browser side effects to `src/hooks/` and pure transforms to `src/core/`.
|
|
66
|
+
* Every new or moved file resides in its designated Atomic Design directory with unidirectional imports only.
|
|
67
|
+
* React Compiler, ESLint, and TypeScript typechecking pass with zero errors and zero rule suppressions.
|