arkaos 2.15.0 → 2.16.0

package/departments/dev/skills/onboard/SKILL.md

@@ -27,363 +27,31 @@ The goal: run one command, and the project is fully registered with stack detect
 | `/dev ecosystem create <name>` | Create a new ecosystem |
 | `/dev ecosystem add <project> --to <ecosystem>` | Add existing project to ecosystem |
 
-## Workflow: /dev onboard <path>
+## Orchestration Overview
 
-### Step 1: Validate Path
+The onboard flow is a 12-step pipeline, split across two reference files:
 
-```python
-python3 "$ARKA_OS/../arka-onboard/scripts/detect-stack.py" "<path>" --json
-```
+**Detection phase** (stack-detection.md):
+1. Validate path — resolve relative, check if already onboarded
+2. Auto-detect stack — `detect-stack.py` returns framework, DB, auth, patterns, MCP profile
+3. Architecture analysis — glob models/controllers/components to classify monolith/api/monorepo/SPA
+4. Git analysis — remotes, branches, commits, contributors
 
-If the path doesn't exist, resolve relative to `$HOME` or common project directories (`~/Herd/`, `~/Projects/`, `~/Code/`).
+**Configuration phase** (mcp-config.md):
+5. Determine MCP profile — map framework to `laravel|nuxt|vue|react|nextjs|full-stack|base`
+6. Ecosystem assignment — create/join/standalone
+7. User confirmation — present analysis summary
+8. Generate `PROJECT.md` in project root
+9. Register in `$ARKA_OS/projects/<name>/`
+10. Apply MCP profile — generate `.mcp.json` + `.claude/settings.local.json`
+11. Create Obsidian docs — Home, Architecture, Projects MOC, Ecosystem MOC
+12. Report — summary + next steps
 
-Check if already onboarded: look for `projects/<name>/PROJECT.md` in `$ARKA_OS`.
+The `ecosystem` subcommands (list/create/add) and error handling also live in mcp-config.md.
 
-### Step 2: Auto-Detect Stack
+## References
 
-Run the bundled detection script:
+Load on demand during execution:
 
-```bash
-python3 "$(dirname "$0")/scripts/detect-stack.py" "<resolved-path>" --json
-```
-
-This returns a JSON report with:
-- **Framework** — Laravel, Nuxt, Vue, React, Next.js, Django, FastAPI, etc.
-- **Language** — PHP, TypeScript, Python, etc.
-- **Stack** — full list of detected technologies
-- **Database** — PostgreSQL, MySQL, SQLite, Supabase
-- **Cache/Queue** — Redis, Horizon
-- **Auth** — Sanctum, Passport, NextAuth, Supabase Auth
-- **Payments** — Stripe, Paddle
-- **CSS** — Tailwind, Sass, Nuxt UI, shadcn/ui
-- **Testing** — Pest, PHPUnit, Vitest, Jest, Playwright
-- **Architecture** — monolith, api-only, monorepo, frontend-spa
-- **Patterns** — Services, Repositories, Actions, DTOs
-- **Conventions** — TypeScript, ESLint, Prettier, PHPStan, Docker
-- **Metrics** — models, controllers, migrations, components, pages, tests
-- **MCP Profile** — recommended profile (laravel/nuxt/vue/react/nextjs/full-stack/base)
-
-If the script is not available, detect manually by reading:
-- `composer.json` — PHP/Laravel dependencies
-- `package.json` — Node.js/frontend dependencies
-- `nuxt.config.ts` / `next.config.ts` — framework config
-- `.env.example` or `.env` — database, cache, queue, payment keys
-- `docker-compose.yml` — infrastructure setup
-
-### Step 3: Architecture Analysis
-
-Glob the project directory to understand its structure:
-
-```
-# Laravel
-app/Models/*.php         → count models
-app/Http/Controllers/    → count controllers
-database/migrations/     → count migrations
-routes/*.php             → count route files
-app/Services/            → Services pattern?
-app/Repositories/        → Repository pattern?
-tests/                   → count tests
-
-# Frontend
-components/**/*.vue|tsx  → count components
-pages/**/*.vue|tsx       → count pages
-composables/             → composables pattern?
-stores/                  → state management?
-```
-
-Determine:
-- **Monolith** — backend + frontend views in one repo
-- **API-only** — backend without frontend views
-- **Monorepo** — `api/` + `frontend/` or `apps/` + `packages/`
-- **Frontend SPA** — no backend, just frontend
-
-### Step 4: Git Analysis
-
-Read-only git commands to understand project history:
-
-```bash
-git -C "<path>" remote -v                    # remotes
-git -C "<path>" branch -a                    # branches
-git -C "<path>" log --oneline -10            # recent commits
-git -C "<path>" shortlog -sn --no-merges | head -5  # top contributors
-git -C "<path>" rev-list --count HEAD        # total commits
-```
-
-### Step 5: Determine MCP Profile
-
-Map detected stack to MCP profile using the same mapping as scaffold:
-
-| Detected Framework | MCP Profile |
-|-------------------|-------------|
-| Laravel | `laravel` |
-| Laravel + ecommerce indicators | `ecommerce` |
-| Nuxt | `nuxt` |
-| Vue (without Nuxt) | `vue` |
-| React (without Next) | `react` |
-| Next.js | `nextjs` |
-| Monorepo (Laravel + frontend) | `full-stack` |
-| Other / Unknown | `base` |
-
-### Step 6: Ecosystem Assignment
-
-If `--ecosystem <name>` was provided:
-1. Read `knowledge/ecosystems.json`
-2. If ecosystem exists, add this project to it
-3. If not, create the ecosystem and add this project
-
-If no ecosystem flag, ask the user:
-- "Create new ecosystem" → ask for name, then create
-- "Join existing ecosystem" → show list, let user pick
-- "Standalone (no ecosystem)" → skip
-
-Ecosystem entry format:
-```json
-{
-  "name": "project-name",
-  "role": "api|frontend|admin|worker|docs|landing",
-  "stack": "Laravel 11",
-  "path": "/absolute/path/to/project"
-}
-```
-
-### Step 7: User Confirmation
-
-Present the analysis summary and ask to proceed:
-
-```
-═══ ARKA OS — Project Analysis ═══
-Name:          <name>
-Path:          <path>
-Framework:     <framework> <version>
-Language:      <language>
-Architecture:  <type>
-Stack:         <technologies>
-Database:      <db>
-Auth:          <auth>
-Testing:       <testing>
-Metrics:       <X> models, <Y> components, <Z> migrations, <W> tests
-MCP Profile:   <profile> (<N> MCPs)
-Ecosystem:     <ecosystem or "standalone">
-Git:           <total commits>, <branches> branches, <contributors> contributors
-═══════════════════════════════════
-
-Proceed with onboarding? (Y/n)
-```
-
-### Step 8: Generate PROJECT.md
-
-Create `PROJECT.md` in the project root with all detected context:
-
-```markdown
-# <name> — WizardingCode Project
-
-## Stack
-- **Framework:** <framework> <version>
-- **Language:** <language>
-- **Database:** <database>
-- **Cache:** <cache>
-- **Queue:** <queue>
-- **Auth:** <auth>
-- **Payments:** <payments>
-- **CSS:** <css>
-- **Testing:** <testing>
-
-## Architecture
-- **Type:** <monolith|api-only|monorepo|frontend-spa>
-- **Patterns:** <Services, Repositories, etc.>
-
-## Key Paths
-- Models: `app/Models/`
-- Controllers: `app/Http/Controllers/`
-- Routes: `routes/`
-- Migrations: `database/migrations/`
-- Tests: `tests/`
-- Components: `components/` or `src/components/`
-
-## Conventions
-- TypeScript: <yes/no>
-- Linting: <ESLint/PHPStan/none>
-- Formatting: <Prettier/none>
-- Docker: <yes/no>
-
-## Ecosystem
-- **Ecosystem:** <name or "standalone">
-- **Role:** <api/frontend/admin/worker>
-
-## Current State
-- Total commits: <N>
-- Active branches: <list>
-- Top contributors: <list>
-- Last commit: <date and message>
-
-## MCPs Active
-- <list from applied profile>
-
-## Decisions
-- **Onboarded:** <date> via ARKA OS v<version>
-- **MCP Profile:** <profile>
-```
-
-### Step 9: Register in ARKA OS
-
-```bash
-mkdir -p "$ARKA_OS/projects/<name>"
-cp "<path>/PROJECT.md" "$ARKA_OS/projects/<name>/PROJECT.md"
-echo "<absolute-path>" > "$ARKA_OS/projects/<name>/.project-path"
-```
-
-The `.project-path` file stores the absolute path so system commands like `/arka standup` can find and reference the actual project.
-
-### Step 10: Apply MCP Profile
-
-```bash
-bash "$ARKA_OS/mcps/scripts/apply-mcps.sh" <profile> --project "<path>"
-```
-
-This generates `.mcp.json` and `.claude/settings.local.json` in the project.
-
-### Step 11: Create Obsidian Documentation
-
-Create pages in the Obsidian vault at `{{OBSIDIAN_VAULT}}`:
-
-**Home page:** `Projects/<name>/Home.md`
-```markdown
----
-type: project
-name: <name>
-stack:
-  - <framework>
-  - <language>
-status: active
-date_created: <YYYY-MM-DD>
-ecosystem: <ecosystem or null>
-tags:
-  - project
-  - <framework-kebab-case>
----
-
-# <name>
-
-> Onboarded into ARKA OS on <date>
-
-## Overview
-- **Framework:** <framework>
-- **Architecture:** <type>
-- **Stack:** <technologies>
-
-## Architecture
-- [[<name> - Architecture]]
-
-## Links
-- Local: `<path>`
-- ARKA OS: `projects/<name>/PROJECT.md`
-
----
-*Part of the [[Projects MOC]]*
-```
-
-**Architecture overview:** `Projects/<name>/Architecture/Overview.md`
-```markdown
----
-type: adr-log
-project: <name>
-date_created: <YYYY-MM-DD>
-tags:
-  - architecture
-  - adr
----
-
-# Architecture — <name>
-
-## ADR-000: Project Onboarded
-- **Date:** <today>
-- **Decision:** Onboarded existing project into ARKA OS
-- **Stack:** <full stack details>
-- **Architecture:** <type> with <patterns>
-- **MCP Profile:** <profile>
-```
-
-**Update Projects MOC:** Append `- [[<name>]]` to the Active Projects section.
-
-**Ecosystem MOC** (if ecosystem assigned): Create or update `Projects/Ecosystems/<ecosystem>.md`:
-```markdown
----
-type: ecosystem
-name: <ecosystem>
-date_updated: <YYYY-MM-DD>
-tags:
-  - ecosystem
-  - project
----
-
-# <ecosystem> Ecosystem
-
-## Projects
-| Project | Role | Stack | Path |
-|---------|------|-------|------|
-| [[<name>]] | <role> | <stack> | `<path>` |
-
----
-*Part of the [[Projects MOC]]*
-```
-
-### Step 12: Report
-
-```
-═══ ARKA OS — Project Onboarded ═══
-Name:          <name>
-Framework:     <framework>
-Architecture:  <type>
-MCPs:          <count> active (<profile> profile)
-Ecosystem:     <ecosystem or "standalone">
-PROJECT.md:    <path>/PROJECT.md
-Obsidian:      Projects/<name>/Home.md
-════════════════════════════════════
-
-Next steps:
-  cd <path>
-  /dev feature "describe your first feature"
-  /dev review    (review current code)
-```
-
-## Workflow: /dev ecosystem list
-
-1. Read `knowledge/ecosystems.json`
-2. Display all ecosystems with their projects:
-
-```
-═══ ARKA OS — Ecosystems ═══
-<ecosystem-name>
-  • <project> (<role>) — <stack> — <path>
-  • <project> (<role>) — <stack> — <path>
-
-<ecosystem-name>
-  • <project> (<role>) — <stack> — <path>
-═════════════════════════════
-```
-
-## Workflow: /dev ecosystem create <name>
-
-1. Read `knowledge/ecosystems.json`
-2. Create new ecosystem entry: `"<name>": { "projects": [] }`
-3. Write back
-4. Confirm creation
-
-## Workflow: /dev ecosystem add <project> --to <ecosystem>
-
-1. Read `knowledge/ecosystems.json`
-2. Read `projects/<project>/PROJECT.md` to get stack info
-3. Read `projects/<project>/.project-path` to get path
-4. Ask user for role (api/frontend/admin/worker/docs/landing)
-5. Add to ecosystem
-6. Write back
-7. Update Ecosystem MOC in Obsidian
-
-## Error Handling
-
-- If path doesn't exist: suggest common directories, ask for correct path
-- If already onboarded: show existing PROJECT.md, ask if re-onboard
-- If no git repo: skip git analysis steps, warn user
-- If detection script fails: fall back to manual file inspection
-- If MCP apply fails: warn but continue (MCPs can be applied later)
-- If Obsidian vault not configured: skip Obsidian steps, warn user
+- `references/stack-detection.md` — Steps 1-4: path validation, `detect-stack.py` output schema, manual detection fallbacks, architecture classification, git analysis commands
+- `references/mcp-config.md` — Steps 5-12: MCP profile mapping, ecosystem assignment, PROJECT.md template, Obsidian page templates, ecosystem subcommand flows, error handling

package/departments/dev/skills/onboard/references/mcp-config.md

@@ -0,0 +1,284 @@
+# arka-onboard — MCP Configuration & Registration
+
+Referenced from SKILL.md. Read only when needed.
+
+## Step 5: Determine MCP Profile
+
+Map detected stack to MCP profile using the same mapping as scaffold:
+
+| Detected Framework | MCP Profile |
+|-------------------|-------------|
+| Laravel | `laravel` |
+| Laravel + ecommerce indicators | `ecommerce` |
+| Nuxt | `nuxt` |
+| Vue (without Nuxt) | `vue` |
+| React (without Next) | `react` |
+| Next.js | `nextjs` |
+| Monorepo (Laravel + frontend) | `full-stack` |
+| Other / Unknown | `base` |
+
+## Step 6: Ecosystem Assignment
+
+If `--ecosystem <name>` was provided:
+1. Read `knowledge/ecosystems.json`
+2. If ecosystem exists, add this project to it
+3. If not, create the ecosystem and add this project
+
+If no ecosystem flag, ask the user:
+- "Create new ecosystem" → ask for name, then create
+- "Join existing ecosystem" → show list, let user pick
+- "Standalone (no ecosystem)" → skip
+
+Ecosystem entry format:
+```json
+{
+  "name": "project-name",
+  "role": "api|frontend|admin|worker|docs|landing",
+  "stack": "Laravel 11",
+  "path": "/absolute/path/to/project"
+}
+```
+
+## Step 7: User Confirmation
+
+Present the analysis summary and ask to proceed:
+
+```
+═══ ARKA OS — Project Analysis ═══
+Name:          <name>
+Path:          <path>
+Framework:     <framework> <version>
+Language:      <language>
+Architecture:  <type>
+Stack:         <technologies>
+Database:      <db>
+Auth:          <auth>
+Testing:       <testing>
+Metrics:       <X> models, <Y> components, <Z> migrations, <W> tests
+MCP Profile:   <profile> (<N> MCPs)
+Ecosystem:     <ecosystem or "standalone">
+Git:           <total commits>, <branches> branches, <contributors> contributors
+═══════════════════════════════════
+
+Proceed with onboarding? (Y/n)
+```
+
+## Step 8: Generate PROJECT.md
+
+Create `PROJECT.md` in the project root with all detected context:
+
+```markdown
+# <name> — WizardingCode Project
+
+## Stack
+- **Framework:** <framework> <version>
+- **Language:** <language>
+- **Database:** <database>
+- **Cache:** <cache>
+- **Queue:** <queue>
+- **Auth:** <auth>
+- **Payments:** <payments>
+- **CSS:** <css>
+- **Testing:** <testing>
+
+## Architecture
+- **Type:** <monolith|api-only|monorepo|frontend-spa>
+- **Patterns:** <Services, Repositories, etc.>
+
+## Key Paths
+- Models: `app/Models/`
+- Controllers: `app/Http/Controllers/`
+- Routes: `routes/`
+- Migrations: `database/migrations/`
+- Tests: `tests/`
+- Components: `components/` or `src/components/`
+
+## Conventions
+- TypeScript: <yes/no>
+- Linting: <ESLint/PHPStan/none>
+- Formatting: <Prettier/none>
+- Docker: <yes/no>
+
+## Ecosystem
+- **Ecosystem:** <name or "standalone">
+- **Role:** <api/frontend/admin/worker>
+
+## Current State
+- Total commits: <N>
+- Active branches: <list>
+- Top contributors: <list>
+- Last commit: <date and message>
+
+## MCPs Active
+- <list from applied profile>
+
+## Decisions
+- **Onboarded:** <date> via ARKA OS v<version>
+- **MCP Profile:** <profile>
+```
+
+## Step 9: Register in ARKA OS
+
+```bash
+mkdir -p "$ARKA_OS/projects/<name>"
+cp "<path>/PROJECT.md" "$ARKA_OS/projects/<name>/PROJECT.md"
+echo "<absolute-path>" > "$ARKA_OS/projects/<name>/.project-path"
+```
+
+The `.project-path` file stores the absolute path so system commands like `/arka standup` can find and reference the actual project.
+
+## Step 10: Apply MCP Profile
+
+```bash
+bash "$ARKA_OS/mcps/scripts/apply-mcps.sh" <profile> --project "<path>"
+```
+
+This generates `.mcp.json` and `.claude/settings.local.json` in the project.
+
+## Step 11: Create Obsidian Documentation
+
+Create pages in the Obsidian vault at `{{OBSIDIAN_VAULT}}`:
+
+**Home page:** `Projects/<name>/Home.md`
+```markdown
+---
+type: project
+name: <name>
+stack:
+  - <framework>
+  - <language>
+status: active
+date_created: <YYYY-MM-DD>
+ecosystem: <ecosystem or null>
+tags:
+  - project
+  - <framework-kebab-case>
+---
+
+# <name>
+
+> Onboarded into ARKA OS on <date>
+
+## Overview
+- **Framework:** <framework>
+- **Architecture:** <type>
+- **Stack:** <technologies>
+
+## Architecture
+- [[<name> - Architecture]]
+
+## Links
+- Local: `<path>`
+- ARKA OS: `projects/<name>/PROJECT.md`
+
+---
+*Part of the [[Projects MOC]]*
+```
+
+**Architecture overview:** `Projects/<name>/Architecture/Overview.md`
+```markdown
+---
+type: adr-log
+project: <name>
+date_created: <YYYY-MM-DD>
+tags:
+  - architecture
+  - adr
+---
+
+# Architecture — <name>
+
+## ADR-000: Project Onboarded
+- **Date:** <today>
+- **Decision:** Onboarded existing project into ARKA OS
+- **Stack:** <full stack details>
+- **Architecture:** <type> with <patterns>
+- **MCP Profile:** <profile>
+```
+
+**Update Projects MOC:** Append `- [[<name>]]` to the Active Projects section.
+
+**Ecosystem MOC** (if ecosystem assigned): Create or update `Projects/Ecosystems/<ecosystem>.md`:
+```markdown
+---
+type: ecosystem
+name: <ecosystem>
+date_updated: <YYYY-MM-DD>
+tags:
+  - ecosystem
+  - project
+---
+
+# <ecosystem> Ecosystem
+
+## Projects
+| Project | Role | Stack | Path |
+|---------|------|-------|------|
+| [[<name>]] | <role> | <stack> | `<path>` |
+
+---
+*Part of the [[Projects MOC]]*
+```
+
+## Step 12: Report
+
+```
+═══ ARKA OS — Project Onboarded ═══
+Name:          <name>
+Framework:     <framework>
+Architecture:  <type>
+MCPs:          <count> active (<profile> profile)
+Ecosystem:     <ecosystem or "standalone">
+PROJECT.md:    <path>/PROJECT.md
+Obsidian:      Projects/<name>/Home.md
+════════════════════════════════════
+
+Next steps:
+  cd <path>
+  /dev feature "describe your first feature"
+  /dev review    (review current code)
+```
+
+## Ecosystem Subcommand Workflows
+
+### /dev ecosystem list
+
+1. Read `knowledge/ecosystems.json`
+2. Display all ecosystems with their projects:
+
+```
+═══ ARKA OS — Ecosystems ═══
+<ecosystem-name>
+  • <project> (<role>) — <stack> — <path>
+  • <project> (<role>) — <stack> — <path>
+
+<ecosystem-name>
+  • <project> (<role>) — <stack> — <path>
+═════════════════════════════
+```
+
+### /dev ecosystem create <name>
+
+1. Read `knowledge/ecosystems.json`
+2. Create new ecosystem entry: `"<name>": { "projects": [] }`
+3. Write back
+4. Confirm creation
+
+### /dev ecosystem add <project> --to <ecosystem>
+
+1. Read `knowledge/ecosystems.json`
+2. Read `projects/<project>/PROJECT.md` to get stack info
+3. Read `projects/<project>/.project-path` to get path
+4. Ask user for role (api/frontend/admin/worker/docs/landing)
+5. Add to ecosystem
+6. Write back
+7. Update Ecosystem MOC in Obsidian
+
+## Error Handling
+
+- If path doesn't exist: suggest common directories, ask for correct path
+- If already onboarded: show existing PROJECT.md, ask if re-onboard
+- If no git repo: skip git analysis steps, warn user
+- If detection script fails: fall back to manual file inspection
+- If MCP apply fails: warn but continue (MCPs can be applied later)
+- If Obsidian vault not configured: skip Obsidian steps, warn user