stack-analyzer

# Stack Analyzer Skill

A meta-skill that analyzes a project's technology stack and recommends or scaffolds appropriate skills for AI-assisted development. This skill runs automatically during `/ai-dev-kit:setup` but can also be invoked manually.

## Design Principles

### Plugin Isolation

**Leave No Trace**: The ai-dev-kit plugin must be completely removable without leaving artifacts. This skill enforces:

| Component | Location | On Uninstall |
|-----------|----------|--------------|
| Generic skills | `plugins/ai-dev-kit/skills/` | Removed with plugin |
| Project-specific skills | Target repo `.claude/skills/` | User's choice |
| Generated manifest | `.claude/skills/_generated.json` | User's choice |

### Generality

All ai-dev-kit skills are **framework-generic**, not tailored to any specific codebase:

| Pattern | Correct | Wrong |
|---------|---------|-------|
| BAML skill | Universal BAML patterns | CodeGraph-DE-specific DTOs |
| Supabase skill | General best practices | Book-Vetting-specific queries |
| Schema alignment | Works with any ORM | Assumes specific models |

## Variables

| Variable | Default | Description |
|----------|---------|-------------|
| AUTO_ACTIVATE | false | Automatically activate recommended generic skills |
| SCAFFOLD_SKILLS | false | Scaffold project-specific skills in target repo |
| OUTPUT_REPORT | true | Generate recommendation report |
| MANIFEST_PATH | .claude/skills/_generated.json | Path for generated manifest |

## Instructions

**MANDATORY** - Follow the Workflow steps below in order.

1. Run `library-detection` skill to get project stack
2. Match detected stack against skill recommendations
3. Report recommended generic skills
4. Optionally scaffold project-specific skills
5. Update generated manifest if skills were created

## Red Flags - STOP and Reconsider

If you're about to:
- Create a skill tailored to a specific codebase (vs generic pattern)
- Put project-specific skills in the plugin directory
- Skip the generated manifest update
- Recommend skills for undetected technologies

**STOP** -> Verify the detection results -> Use generic patterns -> Then proceed

## Workflow

### 1. Detect Project Stack

Invoke the `library-detection` skill first:

```markdown
Read and execute plugins/ai-dev-kit/skills/library-detection/SKILL.md

This returns:
- languages (typescript, python, etc.)
- frameworks (react, fastapi, etc.)
- test_frameworks (vitest, pytest, etc.)
- databases (postgresql, sqlite, etc.)
- build_tools (vite, uv, etc.)
```

### 2. Match Against Skill Recommendations

Load recommendations from `./config/recommendations.yaml` and match:

```yaml
For each detected technology:
  IF matches skill activation rule:
    Add to recommended_skills list
  IF matches scaffold template rule:
    Add to scaffold_candidates list
```

### 3. Generate Report

Create a recommendation report:

```markdown
# Stack Analysis Report

## Detected Stack
- **Languages**: TypeScript, Python
- **Frameworks**: Next.js, FastAPI
- **Database**: PostgreSQL (via Supabase)
- **Test**: Vitest, Pytest
- **AI/ML**: BAML

## Recommended Generic Skills (in plugin)

| Skill | Reason | Status |
|-------|--------|--------|
| baml-integration | BAML detected in baml_src/ | Active |
| supabase-patterns | Supabase dependency found | Active |
| schema-alignment | SQLAlchemy detected | Active |

## Project-Specific Skills (scaffoldable)

| Template | Trigger | Output |
|----------|---------|--------|
| project-research | 3 research subagents found | .claude/skills/{project}-research/ |
| project-domain | Models in src/models/ | .claude/skills/{project}-domain/ |
```

### 4. Scaffold Project-Specific Skills (if enabled)

For each scaffold candidate:

```bash
# 1. Copy template to target repo
cp -r ./templates/{template}/ ${TARGET_REPO}/.claude/skills/{project}-{template}/

# 2. Add generation header to SKILL.md
echo "<!-- Generated by ai-dev-kit:recommend-skills on $(date) -->" | \
  cat - ./templates/{template}/SKILL.md > temp && mv temp SKILL.md

# 3. Customize with project name
sed -i "s/{project}/${PROJECT_NAME}/g" SKILL.md
```

### 5. Update Generated Manifest

Create or update `.claude/skills/_generated.json`:

```json
{
  "generated_by": "ai-dev-kit:recommend-skills",
  "generated_at": "2025-12-24T10:00:00Z",
  "plugin_version": "1.0.0",
  "skills_created": [
    {
      "path": ".claude/skills/book-vetting-research/",
      "template": "project-research",
      "created_at": "2025-12-24T10:00:00Z"
    }
  ],
  "docs_created": [
    "ai-docs/libraries/baml/"
  ],
  "cleanup_instructions": "These files were generated by ai-dev-kit. You may delete them after uninstalling the plugin."
}
```

## Skill Recommendation Rules

### Generic Skills (Activate)

| Skill | Detection Criteria |
|-------|-------------------|
| `baml-integration` | `baml_src/**/*.baml` exists OR `baml-py`/`baml` dependency |
| `supabase-patterns` | `supabase` dependency OR `supabase/migrations/` exists |
| `schema-alignment` | `sqlalchemy`/`prisma`/`django`/`alembic` detected |
| `treesitter-patterns` | `tree-sitter`/`tree_sitter` dependency |
| `security-audit` | Always recommended for production codebases |

### Project-Specific Skills (Scaffold)

| Template | Detection Criteria |
|----------|-------------------|
| `project-research` | `.claude/commands/**/research/**` OR `subagent.*research` pattern |
| `project-domain` | `src/models/**` OR `services/domain/**` exists |
| `project-testing` | Custom test patterns beyond standard frameworks |

## Templates

### project-research

For projects with research-oriented subagents:

```
templates/project-research/
├── SKILL.md          # Customized research patterns
├── cookbook/
│   └── research-workflow.md
└── reference/
    └── source-types.md
```

### project-domain

For projects with rich domain models:

```
templates/project-domain/
├── SKILL.md          # Domain vocabulary and patterns
├── cookbook/
│   └── entity-relationships.md
└── reference/
    └── domain-glossary.md
```

### project-testing

For projects with custom testing requirements:

```
templates/project-testing/
├── SKILL.md          # Custom test patterns
├── cookbook/
│   └── test-fixtures.md
└── reference/
    └── coverage-requirements.md
```

## Integration

### With /ai-dev-kit:setup

Automatically runs during brownfield setup:

```markdown
1. User runs: /ai-dev-kit:setup
2. Setup invokes: stack-analyzer skill
3. Stack analyzer:
   - Detects stack
   - Displays recommendations
   - Prompts: "Activate recommended skills? [y/N]"
   - If yes: marks skills as active
   - Prompts: "Scaffold project-specific skills? [y/N]"
   - If yes: creates skills in target repo
4. Setup continues with remaining steps
```

### With /ai-dev-kit:recommend-skills

Direct invocation:

```bash
# Report only (no changes)
/ai-dev-kit:recommend-skills

# Auto-activate generic skills
/ai-dev-kit:recommend-skills --auto-activate

# Scaffold project-specific skills
/ai-dev-kit:recommend-skills --scaffold

# All options
/ai-dev-kit:recommend-skills --auto-activate --scaffold --output=report.md
```

## Output Schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "detected_stack": {
      "type": "object",
      "description": "Output from library-detection skill"
    },
    "recommended_skills": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "skill": {"type": "string"},
          "reason": {"type": "string"},
          "status": {"enum": ["recommended", "active", "not_applicable"]}
        }
      }
    },
    "scaffold_candidates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "template": {"type": "string"},
          "trigger": {"type": "string"},
          "output_path": {"type": "string"},
          "created": {"type": "boolean"}
        }
      }
    },
    "manifest_updated": {"type": "boolean"},
    "manifest_path": {"type": "string"}
  }
}
```

## Cleanup on Uninstall

When ai-dev-kit plugin is removed, inform user:

```markdown
## ai-dev-kit Uninstall Notice

The following files were generated by ai-dev-kit and persist after uninstall:

**Project-specific skills:**
- .claude/skills/book-vetting-research/
- .claude/skills/book-vetting-domain/

**Documentation:**
- ai-docs/libraries/baml/
- ai-docs/libraries/supabase/

See .claude/skills/_generated.json for full list.

These files are safe to delete if no longer needed.
```