adonisjs-maestro 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Walaff Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# Skills
+
+Reusable agent skills for AdonisJS, Lucid, Inertia, Japa, and full-cycle engineering orchestration.
+
+## Install
+
+### Guided Installer
+
+Use the `adonisjs-maestro` CLI to install the right skills for your stack:
+
+```bash
+npx adonisjs-maestro
+```
+
+Non-interactive examples:
+
+```bash
+npx adonisjs-maestro --stack=vue --yes
+npx adonisjs-maestro --stack=react --global --agent=codex --yes
+npx adonisjs-maestro --skills=maestro,adonisjs,lucid,japa --yes
+```
+
+Available stacks:
+
+| Stack | Skills |
+| --- | --- |
+| `monorepo` | `maestro`, `adonisjs`, `lucid`, `japa` |
+| `hypermedia` | `maestro`, `adonisjs`, `lucid`, `japa` |
+| `react` | `maestro`, `adonisjs`, `lucid`, `japa`, `inertia-react` |
+| `vue` | `maestro`, `adonisjs`, `lucid`, `japa`, `inertia-vue` |
+| `custom` | Choose individual skills |
+
+### Direct Skills CLI
+
+Install the collection with the `skills` CLI:
+
+```bash
+npx skills add lncitador/adonisjs-maestro
+```
+
+For a global install:
+
+```bash
+npx skills add lncitador/adonisjs-maestro -g --yes
+```
+
+Restart your agent after installing so the new skills are loaded.
+
+## Skills
+
+| Skill | Use it for |
+| --- | --- |
+| `maestro` | Orchestrating full-cycle app work: intake, planning, implementation, verification, commit, push, and PR |
+| `adonisjs` | AdonisJS v7 backend work: migrations, models, transformers, controllers, routes, auth, policies, services, events, and review |
+| `lucid` | Lucid ORM and SQL layer: migrations, schema generation, models, relationships, query builders, transactions, factories, and seeders |
+| `inertia-vue` | Vue 3 frontend patterns in AdonisJS + Inertia projects |
+| `inertia-react` | React frontend patterns in AdonisJS + Inertia projects |
+| `japa` | Japa testing in AdonisJS apps: API tests, browser tests, console tests, fakes, swaps, and database setup |
+
+## Recommended Entry Point
+
+Use `maestro` when the task is broader than a single framework question.
+
+```text
+INTAKE -> PLANNING -> BUILD -> VERIFY -> PUBLISH -> DONE
+```
+
+Examples:
+
+```text
+/maestro plan and implement this AdonisJS + Inertia feature.
+/maestro review this PR against the implementation plan.
+/maestro verify, commit, push, and open a PR for this change.
+```
+
+`maestro` coordinates the other skills instead of replacing them. For example, an AdonisJS + Inertia Vue task should usually combine:
+
+- `/maestro` for phase control and workflow gates
+- `/adonisjs` for backend contracts and routing
+- `/lucid` for migrations, models, relationships, query builders, and factories
+- `/inertia-vue` for frontend page/form patterns
+- `/japa` for test strategy and fixtures
+
+## Direct Skill Usage
+
+Use a specialized skill directly when the request is narrow:
+
+```text
+/adonisjs create a controller, route, and validator for posts.
+/lucid create a migration, model relationship, and factory for posts.
+/japa write a functional test with loginAs.
+/inertia-vue fix this Form component.
+/inertia-react type these generated Data props.
+```
+
+## Repository Layout
+
+All skills live under `skills/`. Each folder contains a required `SKILL.md` file and optional resources:
+
+```text
+skills/
+├── maestro/
+├── adonisjs/
+├── lucid/
+├── inertia-vue/
+├── inertia-react/
+└── japa/
+```
+
+The framework skills include references and runbooks for deeper context. The `maestro` skill intentionally has no scripts or references: it is an orchestration layer.
+
+## Development
+
+Use the Skills CLI to search, install, check, and update skills:
+
+```bash
+npm run typecheck
+npm run build
+npx skills find adonisjs
+npx skills check
+npx skills update
+```
+
+Before publishing changes, make sure each skill folder contains a valid `SKILL.md` with YAML frontmatter:
+
+```yaml
+---
+name: skill-name
+description: Use when...
+---
+```
+
+Keep optional resources (`references/`, `scripts/`, `assets/`, `agents/`) only when they directly support the skill.
+
+## Release
+
+Releases are created with `release-it`:
+
+```bash
+npm run release
+```
+
+The release command runs typecheck, tests, and build before bumping the package version, creating the release commit, and tagging it as `v<version>`. Pushing the tag triggers GitHub Actions to publish `adonisjs-maestro` to npm.
+
+Configure npm Trusted Publishing for `.github/workflows/publish.yml` before the first release. The workflow uses GitHub OIDC instead of a long-lived npm token.
+
+## Notes
+
+- These skills assume modern AdonisJS v7 conventions.
+- `lucid` is focused on the ORM/database layer and should be paired with `adonisjs` for controllers, routes, validators, services, and framework-level architecture.
+- `inertia-vue` and `inertia-react` are frontend-layer skills and should be paired with `adonisjs` for backend work.
+- `japa` is focused on testing patterns for AdonisJS apps.
+- `maestro` should be used when a task needs orchestration, phase gates, or publishing workflow discipline.

package/build/bin/run.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import {
+  kernel
+} from "../chunk-ZWBJVZPB.js";
+
+// bin/run.ts
+kernel.handle(["adonisjs-maestro", ...process.argv.slice(2)]).catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/build/chunk-ZWBJVZPB.js

@@ -0,0 +1,217 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// index.ts
+import { HelpCommand, Kernel } from "@adonisjs/ace";
+
+// commands/main.ts
+import { execa } from "execa";
+import { BaseCommand, flags } from "@adonisjs/ace";
+
+// src/stacks.ts
+var SKILLS_REPOSITORY = "lncitador/adonisjs-maestro";
+var AVAILABLE_SKILLS = [
+  "maestro",
+  "adonisjs",
+  "lucid",
+  "japa",
+  "inertia-react",
+  "inertia-vue"
+];
+var STACKS = [
+  {
+    name: "monorepo",
+    label: "Monorepo: API + TanStack",
+    hint: "API/backend workflow without Inertia frontend skills",
+    skills: ["maestro", "adonisjs", "lucid", "japa"]
+  },
+  {
+    name: "hypermedia",
+    label: "Hypermedia",
+    hint: "Server-rendered or hypermedia-oriented AdonisJS app",
+    skills: ["maestro", "adonisjs", "lucid", "japa"]
+  },
+  {
+    name: "react",
+    label: "Fullstack: Inertia React",
+    hint: "AdonisJS + Lucid + Inertia React",
+    skills: ["maestro", "adonisjs", "lucid", "japa", "inertia-react"]
+  },
+  {
+    name: "vue",
+    label: "Fullstack: Inertia Vue",
+    hint: "AdonisJS + Lucid + Inertia Vue",
+    skills: ["maestro", "adonisjs", "lucid", "japa", "inertia-vue"]
+  },
+  {
+    name: "custom",
+    label: "Custom",
+    hint: "Choose individual skills",
+    skills: []
+  }
+];
+function getStack(name) {
+  return STACKS.find((stack) => stack.name === name);
+}
+function parseSkills(value) {
+  const requested = value.split(",").map((skill) => skill.trim()).filter(Boolean);
+  const invalid = requested.filter((skill) => !AVAILABLE_SKILLS.includes(skill));
+  if (invalid.length > 0) {
+    throw new Error(`Unknown skill(s): ${invalid.join(", ")}`);
+  }
+  return [...new Set(requested)];
+}
+function buildSkillsAddArgs(options) {
+  const args = ["skills", "add", SKILLS_REPOSITORY];
+  for (const skill of options.skills) {
+    args.push("--skill", skill);
+  }
+  if (options.global) {
+    args.push("--global");
+  }
+  for (const agent of options.agents ?? []) {
+    args.push("--agent", agent);
+  }
+  if (options.yes) {
+    args.push("--yes");
+  }
+  return args;
+}
+
+// commands/main.ts
+var InstallSkills = class extends BaseCommand {
+  static commandName = "adonisjs-maestro";
+  static description = "Install AdonisJS Maestro agent skills for your stack";
+  async #promptForStack() {
+    if (this.stack) {
+      return this.stack;
+    }
+    const selected = await this.prompt.choice(
+      "Which AdonisJS stack are you using?",
+      STACKS.map((stack) => ({
+        name: stack.name,
+        message: stack.label,
+        hint: stack.hint
+      }))
+    );
+    return selected;
+  }
+  async #promptForCustomSkills() {
+    const answer = await this.prompt.ask(
+      [
+        "Which skills should be installed?",
+        `Available: ${AVAILABLE_SKILLS.join(", ")}`,
+        "Enter a comma-separated list"
+      ].join("\n")
+    );
+    return parseSkills(answer);
+  }
+  #parseAgents() {
+    if (!this.agent) {
+      return [];
+    }
+    return this.agent.split(",").map((agent) => agent.trim()).filter(Boolean);
+  }
+  async #resolveSkills() {
+    if (this.skills) {
+      return parseSkills(this.skills);
+    }
+    const stackName = await this.#promptForStack();
+    const stack = getStack(stackName);
+    if (!stack) {
+      throw new Error(`Unknown stack "${stackName}". Expected one of: ${STACKS.map((item) => item.name).join(", ")}`);
+    }
+    if (stack.name === "custom") {
+      return this.#promptForCustomSkills();
+    }
+    return stack.skills;
+  }
+  #renderCommand(args) {
+    return ["npx", ...args].join(" ");
+  }
+  async run() {
+    const skills = await this.#resolveSkills();
+    if (skills.length === 0) {
+      throw new Error("No skills selected");
+    }
+    const args = buildSkillsAddArgs({
+      skills,
+      global: this.global,
+      agents: this.#parseAgents(),
+      yes: this.yes
+    });
+    this.logger.info(`Installing skills: ${skills.join(", ")}`);
+    this.logger.info(this.#renderCommand(args));
+    if (this.dryRun) {
+      return;
+    }
+    await execa("npx", args, {
+      stdio: this.verbose ? "inherit" : "pipe"
+    });
+    this.logger.success("AdonisJS Maestro skills installed");
+  }
+};
+__decorateClass([
+  flags.string({
+    description: "Stack preset to install: monorepo, hypermedia, react, vue, or custom"
+  })
+], InstallSkills.prototype, "stack", 2);
+__decorateClass([
+  flags.string({
+    description: "Comma-separated list of skills to install"
+  })
+], InstallSkills.prototype, "skills", 2);
+__decorateClass([
+  flags.string({
+    description: 'Target agent. Repeat by comma-separating values, or use "*" for all agents',
+    alias: "a"
+  })
+], InstallSkills.prototype, "agent", 2);
+__decorateClass([
+  flags.boolean({
+    description: "Install globally instead of the current project",
+    alias: "g"
+  })
+], InstallSkills.prototype, "global", 2);
+__decorateClass([
+  flags.boolean({
+    description: "Skip skills CLI confirmation prompts",
+    alias: "y"
+  })
+], InstallSkills.prototype, "yes", 2);
+__decorateClass([
+  flags.boolean({
+    description: "Print the generated npx skills command without running it"
+  })
+], InstallSkills.prototype, "dryRun", 2);
+__decorateClass([
+  flags.boolean({
+    description: "Show command output from the skills CLI",
+    alias: "v"
+  })
+], InstallSkills.prototype, "verbose", 2);
+
+// index.ts
+Kernel.defaultCommand = InstallSkills;
+var kernel = Kernel.create();
+kernel.defineFlag("help", {
+  type: "boolean",
+  description: HelpCommand.description
+});
+kernel.on("help", async (command, $kernel, parsed) => {
+  parsed.args.unshift(command.commandName);
+  await new HelpCommand($kernel, parsed, kernel.ui, kernel.prompt).exec();
+  return $kernel.shortcircuit();
+});
+
+export {
+  kernel
+};

package/build/index.js

@@ -0,0 +1,6 @@
+import {
+  kernel
+} from "./chunk-ZWBJVZPB.js";
+export {
+  kernel
+};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "adonisjs-maestro",
+  "description": "Install AdonisJS Maestro agent skills by stack",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "adonisjs-maestro": "build/bin/run.js"
+  },
+  "exports": {
+    ".": "./build/index.js"
+  },
+  "files": [
+    "build",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepack": "npm run build",
+    "release": "release-it",
+    "release:dry-run": "release-it --dry-run",
+    "test": "node --import=@poppinss/ts-exec --enable-source-maps bin/test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@adonisjs/ace": "^14.1.0",
+    "execa": "^9.6.1"
+  },
+  "devDependencies": {
+    "@japa/assert": "^4.2.0",
+    "@japa/runner": "^5.3.0",
+    "@poppinss/ts-exec": "^1.4.4",
+    "@types/node": "^25.0.0",
+    "release-it": "^20.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "tsup": {
+    "entry": [
+      "./index.ts",
+      "./bin/run.ts"
+    ],
+    "outDir": "./build",
+    "clean": true,
+    "format": "esm",
+    "target": "esnext",
+    "dts": false,
+    "sourcemap": false
+  },
+  "keywords": [
+    "adonisjs",
+    "agent-skills",
+    "skills",
+    "maestro"
+  ],
+  "homepage": "https://github.com/lncitador/adonisjs-maestro#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lncitador/adonisjs-maestro.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lncitador/adonisjs-maestro/issues"
+  },
+  "license": "MIT"
+}