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.

Setup Process

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

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.

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

For Laravel projects, use these enums:

# 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:

# 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.

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:

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

Content:

# 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:

# Write docs/knowledge/index.md

Content:

# 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.

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

# 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).

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

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)