forge-server 0.1.0

package/plugin/skills/project-discovery/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: project-discovery
+description: This skill should be used when exploring and understanding an existing codebase for the first time or when verifying current project patterns. Used by the designer, architect, and inspector agents to read and understand project structure, frameworks, conventions, and existing patterns.
+user-invocable: false
+---
+
+# Project Discovery Skill
+
+## Purpose
+
+Provide a systematic, repeatable methodology for exploring and understanding a codebase. Apply this skill when encountering a project for the first time, when verifying that implementation follows established patterns, or when auditing an existing system for consistency. The output of project discovery is a mental model of the codebase that enables informed decisions by downstream agents (Designer, Architect, Inspector).
+
+---
+
+## Exploration Methodology
+
+Follow these eight steps in order. Each step builds on the previous one. Do not skip steps, but adjust depth based on the agent's needs -- an Architect needs deeper API and data flow analysis; a Designer needs deeper design system analysis; an Inspector needs deeper testing and quality analysis.
+
+### Step 1: Project Configuration
+
+Read the project's root configuration files to establish the technology stack, dependency landscape, and build toolchain.
+
+**Files to read (in priority order)**:
+- `package.json` -- framework, dependencies, scripts, package name, version
+- `tsconfig.json` and `tsconfig.build.json` -- TypeScript configuration, module system, decorator support
+- `nest-cli.json` -- NestJS builder configuration (SWC vs tsc)
+- `.swcrc` -- SWC configuration for testing and building
+- `drizzle.config.ts` -- Database configuration, migration paths
+- `docker-compose.yml` -- Local development services, database configuration
+- `.env.example` or `.env.development` -- Environment variable shape (never read `.env` directly)
+- `Dockerfile` -- Build stages, base images, runtime configuration
+- `bitbucket-pipelines.yml` or `.github/workflows/` -- CI/CD pipeline structure
+- `vitest.config.ts` or `jest.config.ts` -- Test framework configuration
+
+**What to extract**:
+- Framework and version (NestJS, React, Next.js, etc.)
+- Module system (CommonJS vs ESM)
+- Builder (SWC, tsc, esbuild, webpack)
+- Database driver and ORM (Drizzle, Prisma, TypeORM, etc.)
+- Test framework and configuration
+- Key scripts: `start`, `build`, `test`, `db:migrate`, `db:generate`, `lint`
+- Dev dependencies that signal tooling choices (Storybook, Playwright, Husky, etc.)
+
+### Step 2: Directory Structure
+
+Map the project's file organization to identify the architectural pattern.
+
+**Commands to run**:
+- List the top-level directory structure.
+- List the `src/` directory structure (or equivalent entry directory).
+- Identify any monorepo markers (`packages/`, `apps/`, `libs/`, workspace config in `package.json`).
+
+**Patterns to identify**:
+- **Modular NestJS**: `src/{module-name}/{module-name}.module.ts` + controller + service + DTOs
+- **Feature-based**: `src/features/{feature}/` with co-located components, services, tests
+- **Layer-based**: `src/controllers/`, `src/services/`, `src/repositories/`
+- **Monorepo**: `packages/{package-name}/` or `apps/{app-name}/`
+- **Flat**: Everything in `src/` with no sub-organization (flag as a concern)
+
+**What to extract**:
+- Architectural pattern name and description
+- Module/feature list with brief purpose for each
+- Shared/common directories and their purpose
+- Test file location pattern (co-located vs separate `test/` directory)
+- Configuration and infrastructure directories
+
+### Step 3: Entry Points
+
+Identify how the application bootstraps and what happens at startup.
+
+**Files to read**:
+- `src/main.ts` -- NestJS bootstrap, middleware, global pipes, global filters, CORS, dotenv loading
+- `src/app.module.ts` -- Root module, imported modules, global providers
+- `src/app.controller.ts` -- Root routes (if any)
+
+**What to extract**:
+- Bootstrap sequence: what happens before `NestFactory.create()`?
+- Global middleware, pipes, filters, interceptors
+- Module import order and any conditional imports
+- Environment variable loading strategy (dotenv timing, ConfigModule usage)
+- Port configuration, CORS settings, API prefix
+
+### Step 4: Routing and Request Flow
+
+Trace how HTTP requests (or other input) flow through the system.
+
+**Discovery method**:
+- Search for `@Controller` decorators to find all route handlers.
+- Search for `@Get`, `@Post`, `@Put`, `@Patch`, `@Delete` to map endpoints.
+- Search for `@UseGuards` to identify authentication/authorization patterns.
+- Search for `@UseInterceptors` to identify cross-cutting concerns.
+- Search for `@UsePipes` to identify validation patterns.
+
+**What to extract**:
+- Complete route table: method, path, controller, handler, guards
+- Authentication strategy (JWT, API key, session, etc.)
+- Authorization model (RBAC, ABAC, resource-based, etc.)
+- Validation approach (class-validator DTOs, Zod, manual)
+- Error handling pattern (exception filters, global handlers)
+- API versioning strategy (if any)
+
+### Step 5: State and Data Management
+
+Understand how data flows through the application and how state is managed.
+
+**Files to read**:
+- `src/drizzle/` or `src/database/` -- ORM configuration, schema definitions, providers
+- `src/**/schema.ts` or `src/**/entities/` -- Data model definitions
+- `drizzle/` migration directory -- Migration history
+- Any `src/**/dto/` directories -- Data transfer object shapes
+
+**What to extract**:
+- Database schema: tables, columns, types, constraints, indexes, relations
+- ORM pattern: repository pattern, direct query, query builder
+- Connection management: connection pooling, lazy initialization, Proxy patterns
+- Migration strategy: how migrations are generated and applied
+- Seed data: is there a seeding mechanism?
+- Caching layer: Redis, in-memory, none
+
+### Step 6: Design System (Frontend Projects)
+
+For projects with a frontend, discover the existing design system and component library.
+
+**Files and directories to search**:
+- `src/theme/` or `src/styles/` -- Theme definitions, CSS variables, tokens
+- `src/components/` -- Component library structure
+- `src/design-system/` or `src/ui/` -- Dedicated design system directories
+- `.storybook/` -- Storybook configuration
+- `tailwind.config.*` -- Tailwind customization
+- Any `xd-bible.md` or `xd-plan.md` -- Existing design documentation
+- `src/**/*.css`, `src/**/*.scss`, `src/**/*.styled.*` -- Styling approach
+
+**What to extract**:
+- Styling methodology: CSS Modules, styled-components, Tailwind, CSS variables, SCSS
+- Color system: palette definition, semantic tokens, dark mode support
+- Typography: font families, scale, weight usage
+- Spacing: scale system (4px grid, 8px grid, custom)
+- Component hierarchy: atoms, molecules, organisms (or equivalent)
+- Existing component inventory with usage patterns
+- Responsive strategy: breakpoints, mobile-first vs desktop-first
+- Animation/transition patterns
+
+### Step 7: Testing Setup
+
+Understand the testing infrastructure and existing test patterns.
+
+**Files to read**:
+- `vitest.config.ts` or `jest.config.ts` -- Test framework configuration
+- Any `*.spec.ts` or `*.test.ts` files (read 2-3 representative examples)
+- `test/` directory structure (if separate from source)
+- Any `e2e/` or `integration/` test directories
+
+**What to extract**:
+- Test framework and runner (Vitest, Jest, Mocha)
+- Test file naming convention (`.spec.ts` vs `.test.ts`)
+- Test organization pattern (co-located vs centralized)
+- Mocking patterns (what is mocked, how)
+- Coverage configuration and current coverage levels
+- E2E test framework (Playwright, Cypress, Supertest)
+- Test database strategy (in-memory, Docker, shared dev DB)
+- Fixture and factory patterns
+
+### Step 8: Build and Deployment
+
+Understand how the application is built, packaged, and deployed.
+
+**Files to read**:
+- `Dockerfile` -- Build stages, runtime image, exposed ports
+- `docker-compose.yml` -- Local development services
+- `bitbucket-pipelines.yml` or CI config -- Pipeline stages, deployment targets
+- `helm/` or `charts/` -- Kubernetes deployment configuration
+- `k8s/` -- Raw Kubernetes manifests (if any)
+- Any `Makefile` or build scripts
+
+**What to extract**:
+- Build pipeline: stages, parallelism, caching
+- Container strategy: multi-stage build, base image, runtime user
+- Deployment target: Kubernetes (EKS), ECS, Lambda, bare EC2
+- Helm chart structure: values, templates, dependencies
+- Environment promotion: dev -> staging -> production pipeline
+- Secret management: External Secrets, AWS Secrets Manager, env vars
+
+---
+
+## Pattern Extraction
+
+After completing the eight-step exploration, synthesize the findings into pattern observations.
+
+### Naming Conventions
+
+Document the project's naming conventions:
+- File naming: kebab-case, camelCase, PascalCase
+- Class naming: PascalCase with suffix (e.g., `NotificationService`, `UserController`)
+- Variable naming: camelCase, snake_case
+- Database naming: snake_case for tables and columns, singular vs plural table names
+- API route naming: kebab-case, camelCase, plural nouns for resources
+- Environment variable naming: UPPER_SNAKE_CASE with prefix
+
+### Import Patterns
+
+Document how the project handles imports:
+- Path aliases (`@/`, `~/`, `#/`)
+- Barrel exports (`index.ts` files)
+- Relative vs absolute imports
+- Module boundary enforcement (do modules import from each other directly, or through public APIs?)
+
+### Error Handling Patterns
+
+Document the project's error handling approach:
+- Custom exception classes
+- Exception filter hierarchy
+- Error response shape
+- Logging integration
+
+---
+
+## Architecture Fingerprinting
+
+Produce a concise architecture fingerprint -- a summary that any agent can read to understand the project's shape without re-running discovery.
+
+### Fingerprint Format
+
+```
+## Architecture Fingerprint
+
+- **Framework**: NestJS 10.x with SWC builder
+- **Language**: TypeScript 5.x, CommonJS module system
+- **Database**: PostgreSQL 15 via Drizzle ORM (postgres.js driver)
+- **Auth**: JWT with JWKS (Auth0), role-based authorization
+- **API Style**: REST, JSON, `/api/v1` prefix
+- **Testing**: Vitest with SWC plugin, co-located spec files
+- **Deployment**: Docker -> EKS via Helm + ArgoCD
+- **Modules**: {count} modules: {list with one-line descriptions}
+- **Design System**: {description or "N/A for backend-only projects"}
+```
+
+Write this fingerprint to the plan folder as part of the architecture or design document, so other agents do not need to re-discover what has already been mapped.
+
+---
+
+## What to Document vs. What to Skip
+
+### Always Document
+- Framework versions and configuration choices
+- Architectural pattern and module boundaries
+- Database schema and migration state
+- API routes and authentication strategy
+- Naming conventions that deviate from defaults
+- Design system tokens and component inventory (frontend)
+- Testing patterns and coverage state
+- Build and deployment pipeline
+
+### Skip (Do Not Spend Time On)
+- Individual utility function implementations (unless they reveal a pattern)
+- Third-party library internals
+- Generated code (migration SQL files, compiled output)
+- IDE configuration files (`.vscode/`, `.idea/`)
+- Detailed reading of every test file (read 2-3 representative examples)
+- Git history (unless asked to investigate a regression)
+
+---
+
+## Red Flags to Surface
+
+During discovery, actively look for and report these issues:
+
+- **Stubs and placeholders**: Functions that return hardcoded data, TODO comments in production code, `throw new Error('Not implemented')`. These indicate incomplete work.
+- **Dead code**: Unused imports, unreachable functions, commented-out blocks. These indicate maintenance debt.
+- **Inconsistent patterns**: Two modules using different naming conventions, two services using different error handling approaches. These indicate drift.
+- **Missing tests**: Modules with no corresponding test files, or test files with zero assertions. These indicate quality gaps.
+- **Hardcoded configuration**: Database URLs, API keys, or service endpoints hardcoded in source files instead of environment variables. These indicate deployment risks.
+- **Circular dependencies**: Module A imports from Module B which imports from Module A. These indicate architectural issues.
+- **Oversized modules**: A single module with 10+ services or a single service with 500+ lines. These indicate decomposition opportunities.
+- **Missing error handling**: Catch blocks that swallow errors, API endpoints with no validation, database queries with no error handling.
+- **Security concerns**: Secrets in source code, disabled CORS, missing authentication on endpoints that should be protected.
+
+Report red flags with severity, location, and a brief note on impact. Do not attempt to fix them during discovery -- that is the implementation agents' job. Discovery is read-only.
+
+---
+
+## Adapting Depth by Agent Role
+
+### Architect Discovery
+Focus on Steps 1-5 and Step 8 (configuration, structure, entry points, routing, data, deployment). Skim Step 6 (design system) and Step 7 (testing) unless the project is frontend-heavy. The Architect needs to understand system boundaries, data flow, and infrastructure.
+
+### Designer Discovery
+Focus on Steps 1-2 and Step 6 (configuration, structure, design system). Skim Steps 3-5 (entry points, routing, data) for context but do not deep-dive into backend patterns. The Designer needs to understand the frontend stack, existing components, and visual language.
+
+### Inspector Discovery
+Focus on Steps 4-5 and Step 7 (routing, data, testing). Read Steps 1-3 for context. The Inspector needs to understand what should be tested, what is currently tested, and where quality gaps exist. Step 8 (deployment) matters for verifying that builds pass and configurations are correct.
+
+---
+
+## Output Requirements
+
+Discovery must produce structured output, not just internal understanding. Write findings using the **terminal-presentation** skill for user-facing summaries, and write detailed findings to plan documents when requested by the invoking agent.
+
+At minimum, produce:
+1. An architecture fingerprint (see format above).
+2. A list of discovered modules/features with one-line descriptions.
+3. A list of red flags (if any) with severity and location.
+4. A list of patterns and conventions observed.
+
+If the invoking agent requests a full discovery document, write it to `docs/plans/{plan-folder}/discovery.md` with all eight steps documented.

package/plugin/skills/search/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: search
+description: Search code and knowledge across indexed repos using AI-ranked results. Far better than grep.
+version: 0.1.0
+---
+
+# /search — Intelligent Code & Knowledge Search
+
+Search an indexed codebase using Forge's 5-signal ranking engine. Returns results ranked by vector similarity, graph centrality, recency, change frequency, and observation count — far more relevant than raw text matching.
+
+## Prerequisites
+
+The repo must be registered and indexed with Forge. If not, suggest running `/index-repo` first.
+
+## Behavior
+
+**Code search** (default): Call `mcp__dk-forge__get_codebase_context` with the user's query.
+
+```
+/search authentication middleware
+/search how do API endpoints handle errors
+/search database connection setup
+```
+
+**Knowledge search**: When the query is about patterns, decisions, or conventions rather than specific code, call `mcp__dk-forge__search_knowledge`.
+
+```
+/search pattern: how do we handle auth
+/search decision: why did we choose postgres
+/search convention: naming for API routes
+```
+
+**Combined search**: For broad queries, run both `get_codebase_context` and `search_knowledge` in parallel and present unified results.
+
+## Query Interpretation
+
+- Identify intent: code location vs. pattern/convention vs. architecture decision.
+- For code queries, pass `detail: "full"` to get complete file contents. Use `detail: "skeleton"` for overview, `detail: "paths"` for just file paths.
+- For knowledge queries, optionally filter by `category`: `gotcha`, `pattern`, `decision`, `convention`.
+- Set `include_tests: true` only when the user explicitly asks about test code.
+
+## Output Format
+
+Present results clearly:
+1. **File path** with line numbers for code results.
+2. **Relevance context** — why this result matched (which signals contributed).
+3. **Code snippet** — the relevant section, not the entire file.
+4. For knowledge results, include the confidence score and category.
+
+## Cross-Repo Search
+
+When working in a multi-repo environment, results from other indexed repos may appear. Include the repo name when presenting cross-repo results. Disable with `include_cross_repo: false` if the user only wants current-repo results.
+
+## Fallback
+
+If the repo is not indexed (no Qdrant collections), fall back to built-in `Grep` and `Glob` tools and suggest indexing for better results.