extracting-ai-context

# Extracting AI Context from workflow-kotlin

Manages the extraction of version-matched AI skills and AGENTS.md context from
workflow-kotlin library JARs into the correct locations for your AI coding agent.

## Prerequisites

The project must apply the workflow-kotlin AI context Gradle plugin:

```groovy
// build.gradle / build.gradle.kts
plugins {
  id("com.squareup.workflow1.ai-context") version "<workflow-version>"
}
```

## Quick Start

Run the extraction task — this is the primary command:

```bash
./gradlew extractAiContext
```

This extracts all skills to `.agents/skills/` and merges workflow-kotlin guidance
into `AGENTS.md`. This works out of the box for **Amp, Cursor, Codex, GitHub Copilot,
Gemini CLI, and OpenCode**.

## Agent-Specific Setup

### Claude Code Users

Claude Code uses `.claude/skills/` instead of `.agents/skills/`. To support both:

```bash
./gradlew extractAiContext --tools=amp,claude-code
```

Then create a `CLAUDE.md` symlink so Claude Code picks up the guidance:

```bash
ln -sf AGENTS.md CLAUDE.md
echo "CLAUDE.md" >> .gitignore
```

### Other Agents

The `--tools` flag accepts any agent name from the Agent Skills standard.
Common options:

| Agent | Flag | Skills Directory |
|---|---|---|
| Amp, Cursor, Codex, Copilot, Gemini CLI | `amp` (default) | `.agents/skills/` |
| Claude Code | `claude-code` | `.claude/skills/` |
| Goose | `goose` | `.goose/skills/` |
| Windsurf | `windsurf` | `.windsurf/skills/` |
| Roo Code | `roo` | `.roo/skills/` |

Multiple agents: `--tools=amp,claude-code,goose`

## What Gets Extracted

### Skills
Version-matched skills from workflow-kotlin JARs on your classpath:

- **create-workflow** — Creating StatefulWorkflow and StatelessWorkflow classes
- **workflow-testing** — Unit testing with testRender / RenderTester
- **workflow-integration-testing** — Integration testing with renderForTest / WorkflowTurbine
- **extracting-ai-context** — This skill (self-referential for future re-runs)

### AGENTS.md
The root workflow-kotlin project guide is merged into your `AGENTS.md` using
injection markers. Your existing content is preserved — the injected block is
clearly delimited:

```
<!-- workflow-kotlin-AGENTS-injection:START -->
... workflow-kotlin guidance ...
<!-- workflow-kotlin-AGENTS-injection:END -->
```

## Updating After a Version Bump

When you update your workflow-kotlin dependency version, re-run the extraction
to get version-matched skills and guidance:

```bash
./gradlew extractAiContext
```

The injection markers in `AGENTS.md` ensure the old content is cleanly replaced.
Skills in `.agents/skills/` are overwritten with the new versions.

## Preview Mode

See what would be extracted without writing files:

```bash
./gradlew extractAiContext --preview
```

## Gitignore

Add extracted skill directories to `.gitignore` since they're generated from JARs:

```gitignore
# Extracted AI context (generated by extractAiContext task)
.agents/skills/create-workflow/
.agents/skills/workflow-testing/
.agents/skills/workflow-integration-testing/
.agents/skills/extracting-ai-context/
```

Do NOT gitignore `AGENTS.md` — it contains your project-specific content
alongside the injected workflow-kotlin block.

## Troubleshooting

### No skills extracted
- Verify the plugin is applied: check for `com.squareup.workflow1.ai-context` in your build file
- Ensure workflow-kotlin dependencies are on the classpath (e.g., `workflow-core`, `workflow-testing`)
- Run with `--info` for verbose output: `./gradlew extractAiContext --info`

### Skills are outdated
- Re-run `./gradlew extractAiContext` after updating your workflow-kotlin version
- Check that Gradle resolved the new version: `./gradlew dependencies | grep workflow`