# Setup

> Detect project stack and generate knowledge schema. Use when setting up knowledge-garden in a new project.

- Skill: `oaa-dev/setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oaa-dev/setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oaa-dev/setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: oaa-dev (https://skillmd.com/u/oaa-dev)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/oaa-dev/setup

---


# Knowledge Garden Setup

**Purpose:** Detect the project's tech stack, generate a stack-appropriate `docs/knowledge/schema.yaml`, and create the knowledge directory structure.

## Overview

This skill runs once per project to bootstrap the knowledge garden. It detects whether the project uses Laravel, Next.js, or both, then generates a schema with enum values tailored to that stack.

---

<critical_sequence name="setup-flow" enforce_order="strict">

## Setup Process

<step number="1" required="true">
### Step 1: Detect Stack

Run these checks in parallel to identify the project stack:

**Laravel indicators:**
```
Glob: pattern="artisan"
Glob: pattern="composer.json"
Glob: pattern="app/Models/*.php"
```

**Next.js indicators:**
```
Glob: pattern="next.config.*"
Glob: pattern="package.json"
```

If `package.json` exists, read it and check for `"next"` in dependencies or devDependencies.

**Classification:**
- **Laravel only**: `artisan` or `composer.json` exists, no Next.js dependency
- **Next.js only**: `next.config.*` exists or `package.json` has `next` dependency, no `artisan`
- **Full-stack**: both Laravel and Next.js indicators present
- **Unknown**: neither detected
</step>

<step number="2" required="true" depends_on="1">
### Step 2: Confirm With User

Present the detected stack and ask for confirmation:

```
Detected stack: [Laravel / Next.js / Full-stack (Laravel + Next.js) / Unknown]

Is this correct?
1. Yes, proceed with [detected stack]
2. Laravel only
3. Next.js only
4. Full-stack (Laravel + Next.js)
```

Wait for user response before proceeding.

If "Unknown" was detected, skip the confirmation and ask directly which stack to use.
</step>

<step number="3" required="true" depends_on="2">
### Step 3: Generate Schema

Based on the confirmed stack, generate `docs/knowledge/schema.yaml`.

**For Laravel projects, use these enums:**

```yaml
# Knowledge Garden Schema - Laravel
# Generated by knowledge-garden setup

problem_type:
  - build_error
  - test_failure
  - runtime_error
  - performance_issue
  - database_issue
  - security_issue
  - ui_bug
  - integration_issue
  - logic_error
  - config_error
  - queue_issue
  - authorization_issue

component:
  - eloquent_model
  - controller
  - middleware
  - service
  - repository
  - form_request
  - resource
  - dto
  - enum
  - migration
  - factory
  - seeder
  - blade_view
  - livewire
  - job
  - event
  - observer
  - notification
  - mail
  - policy
  - scope
  - cast
  - action
  - api_route
  - artisan_command
  - test

root_cause:
  - missing_relationship
  - missing_eager_load
  - missing_index
  - wrong_query
  - scope_issue
  - n_plus_one
  - queue_failure
  - config_error
  - logic_error
  - missing_validation
  - missing_policy
  - missing_middleware
  - cache_issue
  - wrong_cast
  - wrong_enum_value
  - dto_mismatch
  - missing_observer
  - event_not_dispatched

severity:
  - critical
  - high
  - medium
  - low

resolution_type:
  - code_fix
  - migration
  - config_change
  - test_fix
  - dependency_update
  - environment_setup

category_map:
  build_error: build-errors
  test_failure: test-failures
  runtime_error: runtime-errors
  performance_issue: performance-issues
  database_issue: database-issues
  security_issue: security-issues
  ui_bug: ui-bugs
  integration_issue: integration-issues
  logic_error: logic-errors
  config_error: config-errors
  queue_issue: queue-issues
  authorization_issue: authorization-issues
```

**For Next.js projects, use these enums:**

```yaml
# Knowledge Garden Schema - Next.js
# Generated by knowledge-garden setup

problem_type:
  - build_error
  - type_error
  - runtime_error
  - performance_issue
  - hydration_error
  - routing_issue
  - api_error
  - state_issue
  - styling_issue
  - deployment_issue
  - validation_error

component:
  - page
  - layout
  - component
  - api_route
  - middleware
  - server_action
  - client_component
  - server_component
  - hook
  - context
  - store
  - utility
  - config
  - type_definition
  - zod_schema
  - enum_constant
  - service_client
  - test

root_cause:
  - hydration_mismatch
  - missing_use_client
  - wrong_data_fetching
  - stale_cache
  - wrong_import
  - type_error
  - state_leak
  - missing_suspense
  - wrong_revalidation
  - env_config
  - schema_mismatch
  - wrong_type_assertion
  - missing_validation

severity:
  - critical
  - high
  - medium
  - low

resolution_type:
  - code_fix
  - config_change
  - type_fix
  - dependency_update
  - environment_setup

category_map:
  build_error: build-errors
  type_error: type-errors
  runtime_error: runtime-errors
  performance_issue: performance-issues
  hydration_error: hydration-errors
  routing_issue: routing-issues
  api_error: api-errors
  state_issue: state-issues
  styling_issue: styling-issues
  deployment_issue: deployment-issues
  validation_error: validation-errors
```

**For full-stack projects:** Merge both schemas. Combine all enum values (deduplicate where they overlap) and include both category maps.
</step>

<step number="4" required="true" depends_on="3">
### Step 4: Create Directory Structure

```bash
mkdir -p docs/knowledge/solutions
mkdir -p docs/knowledge/modules
mkdir -p docs/knowledge/patterns
mkdir -p docs/knowledge/archive
```

Create the initial critical patterns file:

```bash
# Write docs/knowledge/patterns/critical-patterns.md
```

Content:
```markdown
# Critical Patterns

Patterns promoted from solutions that must be followed to prevent recurring issues. Check this file before implementing features.

<!-- Add patterns using the /compound command with "Add to Required Reading" option -->
```

Create the initial empty knowledge index:

```bash
# Write docs/knowledge/index.md
```

Content:
```markdown
# Knowledge Index
<!-- Auto-generated by knowledge-index skill. Regenerate with /knowledge-garden::reindex -->
<!-- Updated: YYYY-MM-DD -->
<!-- Solutions: 0 -->

## Critical Patterns

## Solutions
| File | Module | Type | Component | Severity | Date | Tags |
|------|--------|------|-----------|----------|------|------|
```

Replace `YYYY-MM-DD` with the current date.
</step>

<step number="5" required="true" depends_on="4">
### Step 5: Write Config File

Create `knowledge-garden.local.md` in the project root:

```markdown
# Knowledge Garden Configuration

- **Stack**: [laravel / nextjs / fullstack]
- **Schema**: docs/knowledge/schema.yaml
- **Solutions**: docs/knowledge/solutions/
- **Modules**: docs/knowledge/modules/
- **Patterns**: docs/knowledge/patterns/
- **Archive**: docs/knowledge/archive/
- **Setup date**: [YYYY-MM-DD]
```

Add `knowledge-garden.local.md` to `.gitignore` if it exists (this is a local config file).
</step>

<step number="6" required="true" depends_on="5">
### Step 6: Confirm Setup

Present a summary:

```
Knowledge Garden setup complete.

Stack: [detected stack]
Schema: docs/knowledge/schema.yaml ([N] problem types, [N] components, [N] root causes)
Directories created:
  - docs/knowledge/solutions/
  - docs/knowledge/modules/
  - docs/knowledge/patterns/
  - docs/knowledge/archive/

Next steps:
1. Run /generate-module-docs to index your project modules
2. After solving a problem, the knowledge-docs skill will capture it
3. Run /knowledge-insights periodically to see patterns
```
</step>

</critical_sequence>

---

## Error Handling

**No stack detected:**
- Ask user to specify manually
- Proceed with chosen stack

**Schema already exists:**
- Warn user: "docs/knowledge/schema.yaml already exists. Overwrite? (y/n)"
- If no, skip schema generation but continue with directory creation

**Directory already exists:**
- Skip creation silently (mkdir -p handles this)