name: ai-context-writer
description: Create and update ai-context.md files that document modules for AI assistants. Use when adding documentation for packages, apps, or external references that should be discoverable via /modules commands.

AI Context Writer Skill

Use this skill when creating or updating ai-context.md files that document modules in the codebase. These files are indexed by the context-crawler and surfaced via /modules, /module, and /module-search commands.

File Location

Context files must be named exactly ai-context.md and placed at the root of the module:

packages/my-package/ai-context.md    # Internal module
apps/my-app/ai-context.md            # Internal module
.context/external-lib/ai-context.md  # External reference (submodule)

Required Structure

Frontmatter (YAML)

---
path: packages/my-package
summary: One-line description mentioning purpose and key technologies
tags: [effect, http-client, sdk-wrapper]
---

Frontmatter Fields:
- path - Module identifier (relative path from repo root)
- summary - Single sentence, concise description for module listings
- tags - Optional categorization for search (technologies, domains)

Markdown Body Sections

# Module Name

High-level overview paragraph explaining the module's purpose.

## Architecture

┌──────────────────┐
│    Component     │
└──────────────────┘
        │
        ▼
┌──────────────────┐
│     Service      │
└──────────────────┘

Brief explanation of the architecture diagram.

## Core Modules

| Module | Purpose |
|--------|---------|
| `Service.ts` | Main service implementation |
| `Client.ts` | HTTP client wrapper |

## Usage Patterns

### Basic Usage

```typescript
import * as MyModule from "@/packages/my-package"
import { Effect } from "effect"

const program = Effect.gen(function* () {
  const service = yield* MyModule.Service
  return yield* service.doThing()
})

Key Patterns

Pattern Name

Description of when and why to use this pattern.

// Example code

Design Decisions

AD-1: Decision Title
Explanation of the decision and trade-offs.

AD-2: Another Decision
Why this approach was chosen over alternatives.

Dependencies

• effect - Core Effect library
• @effect/platform - Platform abstractions

Spec Reference

• specs/my-feature/DESIGN.md

## Section Guidelines

### Architecture Diagram

Use simple ASCII box-and-arrow diagrams:

┌──────────────┐ ┌──────────────┐
│ Service │────▶│ Client │
└──────────────┘ └──────────────┘
│
▼
┌──────────────┐
│ Repository │
└──────────────┘

Characters: `┌ ┐ └ ┘ │ ─ ▼ ▲ ◀ ▶ ────▶`

### Core Modules Table

Quick reference for key files:

```markdown
| Module | Purpose |
|--------|---------|
| `ParallelClient.ts` | HTTP client with Effect integration |
| `ParallelRun.ts` | Async task execution |
| `Errors.ts` | Tagged error types |

Usage Patterns

Always include:
- Full imports with namespace pattern (import * as X)
- Effect.gen for effectful code
- Layer construction if services are involved

import * as MyService from "@/packages/my-service"
import { Effect, Layer } from "effect"

const program = Effect.gen(function* () {
  const svc = yield* MyService.Service
  return yield* svc.operation()
})

const live = program.pipe(
  Effect.provide(MyService.Live)
)

Design Decisions

Use AD-N format for traceability:

**AD-1: Use Effect.gen over flatMap chains**
Effect.gen provides cleaner syntax and better stack traces. The generator pattern
makes sequential operations readable without callback nesting.

**AD-2: Schema.TaggedStruct for all domain types**
Automatic discriminator and Data equality support. Enables pattern matching
with Match.typeTags.

Dependencies

List external packages the module depends on:

## Dependencies

- `effect` - Core Effect types and functions
- `@effect/platform` - FileSystem, HttpClient, Terminal
- `@effect/schema` - Runtime validation and serialization

Summary Writing

The summary is critical - it appears in /modules listings.

Good summaries:
- "Effect wrapper for Parallel AI SDK - web search, content extraction, and async task runs"
- "React frontend with Effect-Atom state management and TanStack Router"
- "SQLite-backed workflow engine for durable execution patterns"

Bad summaries:
- "A module for doing stuff" (too vague)
- "This is the main package that handles various functionality" (no specifics)

Summary formula:
[Primary purpose] - [key feature 1], [key feature 2], and [key feature 3]

Discovery and Indexing

Context files are indexed by context-crawler.ts:

1. Recursively finds all ai-context.md files
2. Extracts frontmatter (path, summary, tags)
3. Falls back to first paragraph if no summary
4. Excludes node_modules, .git, dist, build, .turbo

Module Classification

• Internal: Local ai-context.md files in packages/apps
• External: Submodules from .gitmodules (may lack ai-context.md)

External modules without context files show: (grep for implementation details)

Commands for Discovery

# List all modules with summaries
/modules

# Get full content of specific module
/module packages/parallel

# Search modules by pattern
/module-search http

Complete Example

---
path: packages/parallel
summary: Effect wrapper for Parallel AI SDK - web search, content extraction, and async task runs
tags: [effect, sdk-wrapper, parallel-ai, http-client]
---

# Parallel SDK Effect Wrapper

Effect-native wrapper for the Parallel AI SDK. Injects Effect's HttpClient as the
fetch implementation, providing typed errors, deferred computation patterns, and
composable layer construction.

## Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         User Code                                │
│                    (Effect programs)                             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      ParallelClient                              │
│    ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐    │
│    │   search()   │  │  extract()   │  │   createRun()    │    │
│    └──────────────┘  └──────────────┘  └──────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Effect HttpClient                             │
│              (injected via Layer.provide)                        │
└─────────────────────────────────────────────────────────────────┘

## Core Modules

| Module | Purpose |
|--------|---------|
| `ParallelClient.ts` | Service interface with Effect operations |
| `ParallelClientLive.ts` | Live implementation using HttpClient |
| `ParallelRun.ts` | Async run execution with polling |
| `Errors.ts` | Tagged error types for failure handling |

## Usage Patterns

### Basic Search

```typescript
import * as Parallel from "@/packages/parallel"
import { Effect } from "effect"

const program = Effect.gen(function* () {
  const client = yield* Parallel.ParallelClient
  const results = yield* client.search({ query: "Effect TypeScript" })
  return results
})

const runnable = program.pipe(
  Effect.provide(Parallel.Live)
)

Error Handling

import * as Parallel from "@/packages/parallel"
import { Effect } from "effect"

const safe = program.pipe(
  Effect.catchTag("ParallelApiError", (e) =>
    Effect.succeed({ error: e.message })
  ),
  Effect.catchTag("ParallelNetworkError", () =>
    Effect.succeed({ error: "Network unavailable" })
  )
)

Design Decisions

AD-1: Inject HttpClient via Layer
Enables testing with mock HTTP responses. Production uses FetchHttpClient,
tests use a custom client that returns canned responses.

AD-2: Tagged errors for all failure modes
ParallelApiError, ParallelNetworkError, ParallelTimeoutError. Enables
precise error handling with catchTag.

Dependencies

• effect - Core runtime
• @effect/platform - HttpClient abstraction
• parallel-sdk - Underlying SDK (via .context/parallel-sdk-typescript)

Spec Reference

• specs/parallel/DESIGN.md
  ```

When to Use This Skill

• Adding a new package or app that should be discoverable
• Documenting an existing module for AI assistants
• Creating context for external libraries added as submodules
• Updating documentation after significant refactoring
• Ensuring modules appear in /modules listings

Key Principles

1. Frontmatter is required - path and summary enable indexing
2. Summary is critical - appears in all module listings
3. Architecture diagrams - visual overview aids understanding
4. Usage patterns with imports - show how to actually use the module
5. Design decisions - explain why, not just what
6. Code examples compile - include all necessary imports
7. Namespace imports - always import * as X from