feat: extract @agentspec/codegen — provider-agnostic code generation

.github/workflows/publish.yml

@@ -75,13 +75,30 @@ jobs:
           cd packages/mcp-server
           npm publish --access public --provenance
 
+      - name: Resolve workspace deps for codegen
+        run: |
+          SDK_VER=$(node -p "require('./packages/sdk/package.json').version")
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('./packages/codegen/package.json'));
+            pkg.dependencies['@agentspec/sdk'] = pkg.dependencies['@agentspec/sdk'].replace('workspace:*', '$SDK_VER');
+            fs.writeFileSync('./packages/codegen/package.json', JSON.stringify(pkg, null, 2));
+          "
+
+      - name: Publish @agentspec/codegen
+        run: |
+          cd packages/codegen
+          npm publish --access public --provenance
+
       - name: Resolve workspace deps for adapter-claude
         run: |
           SDK_VER=$(node -p "require('./packages/sdk/package.json').version")
+          CODEGEN_VER=$(node -p "require('./packages/codegen/package.json').version")
           node -e "
             const fs = require('fs');
             const pkg = JSON.parse(fs.readFileSync('./packages/adapter-claude/package.json'));
             pkg.dependencies['@agentspec/sdk'] = pkg.dependencies['@agentspec/sdk'].replace('workspace:*', '$SDK_VER');
+            pkg.dependencies['@agentspec/codegen'] = pkg.dependencies['@agentspec/codegen'].replace('workspace:*', '$CODEGEN_VER');
             fs.writeFileSync('./packages/adapter-claude/package.json', JSON.stringify(pkg, null, 2));
           "
 
@@ -93,12 +110,12 @@ jobs:
       - name: Resolve workspace deps for cli
         run: |
           SDK_VER=$(node -p "require('./packages/sdk/package.json').version")
-          ADAPTER_VER=$(node -p "require('./packages/adapter-claude/package.json').version")
+          CODEGEN_VER=$(node -p "require('./packages/codegen/package.json').version")
           node -e "
             const fs = require('fs');
             const pkg = JSON.parse(fs.readFileSync('./packages/cli/package.json'));
             pkg.dependencies['@agentspec/sdk'] = pkg.dependencies['@agentspec/sdk'].replace('workspace:*', '$SDK_VER');
-            pkg.dependencies['@agentspec/adapter-claude'] = pkg.dependencies['@agentspec/adapter-claude'].replace('workspace:*', '$ADAPTER_VER');
+            pkg.dependencies['@agentspec/codegen'] = pkg.dependencies['@agentspec/codegen'].replace('workspace:*', '$CODEGEN_VER');
             fs.writeFileSync('./packages/cli/package.json', JSON.stringify(pkg, null, 2));
           "
 
@@ -116,5 +133,6 @@ jobs:
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "- \`@agentspec/sdk@${VERSION}\`" >> $GITHUB_STEP_SUMMARY
           echo "- \`@agentspec/mcp@${VERSION}\`" >> $GITHUB_STEP_SUMMARY
-          echo "- \`@agentspec/adapter-claude@${VERSION}\`" >> $GITHUB_STEP_SUMMARY
+          echo "- \`@agentspec/codegen@${VERSION}\`" >> $GITHUB_STEP_SUMMARY
+          echo "- \`@agentspec/adapter-claude@${VERSION}\` (deprecated shim)" >> $GITHUB_STEP_SUMMARY
           echo "- \`@agentspec/cli@${VERSION}\`" >> $GITHUB_STEP_SUMMARY

.github/workflows/release.yml

@@ -61,7 +61,7 @@ jobs:
       - name: Update package versions
         run: |
           NEW_VER="${{ steps.semver.outputs.new }}"
-          for pkg in packages/sdk packages/mcp-server packages/adapter-claude packages/cli; do
+          for pkg in packages/sdk packages/mcp-server packages/codegen packages/adapter-claude packages/cli; do
             (cd "$pkg" && npm version "$NEW_VER" --no-git-tag-version)
           done
 
@@ -77,6 +77,7 @@ jobs:
           NEW_VER="${{ steps.semver.outputs.new }}"
           git add packages/sdk/package.json \
                   packages/mcp-server/package.json \
+                  packages/codegen/package.json \
                   packages/adapter-claude/package.json \
                   packages/cli/package.json \
                   packages/operator/helm/agentspec-operator/Chart.yaml
@@ -105,7 +106,7 @@ jobs:
             echo '```bash'
             echo "npm install @agentspec/sdk@${NEW_VER}"
             echo "npm install @agentspec/mcp@${NEW_VER}"
-            echo "npm install @agentspec/adapter-claude@${NEW_VER}"
+            echo "npm install @agentspec/codegen@${NEW_VER}"
             echo "npm install -g @agentspec/cli@${NEW_VER}"
             echo '```'
           } > /tmp/release-notes.md

CHANGELOG.md

@@ -6,6 +6,14 @@ Versions follow [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [Unreleased]
+
+### Fixed
+
+- `@agentspec/codegen`: response parser now tolerates multiple ```json fenced blocks and conversational preamble in LLM output. Previously `agentspec generate` could throw "Provider did not return valid JSON" when the model legitimately split its response into a metadata block and a files block, or prefixed a batch header before the JSON. The parser now iterates every fence, parses each, and merges `files` / `installCommands` / `envVars` across blocks. Fix in commit `f0eb12f`, covered by 4 new cases in `response-parser.test.ts`.
+
+---
+
 ## [0.1.0] - 2026-02-27
 
 ### Added

docs/.vitepress/config.mts

@@ -58,9 +58,10 @@ export default defineConfig({
             text: 'Capabilities',
             collapsed: false,
             items: [
-              { text: 'Add Tools',      link: '/guides/add-tools' },
-              { text: 'Add Memory',     link: '/guides/add-memory' },
-              { text: 'Add Guardrails', link: '/guides/add-guardrails' },
+              { text: 'Add Tools',             link: '/guides/add-tools' },
+              { text: 'Add Memory',            link: '/guides/add-memory' },
+              { text: 'Add Guardrails',        link: '/guides/add-guardrails' },
+              { text: 'Provider Authentication', link: '/guides/provider-auth' },
             ],
           },
           {

docs/CONTRIB.md

@@ -23,7 +23,7 @@ pnpm test        # all tests must pass before you start
 
 | Command | What it does |
 |---------|--------------|
-| `pnpm build` | Build all packages (`sdk` → `adapter-claude` → `cli`, `sidecar`) |
+| `pnpm build` | Build all packages (`sdk` → `codegen` → `cli`, `sidecar`) |
 | `pnpm test` | Run all unit/integration tests |
 | `pnpm lint` | TypeScript type-check all packages |
 | `pnpm typecheck` | TypeScript type-check all packages (alias of lint) |
@@ -54,7 +54,7 @@ make docs-preview # preview built site locally
 ```bash
 pnpm --filter @agentspec/sdk          test
 pnpm --filter @agentspec/cli          test
-pnpm --filter @agentspec/adapter-claude test
+pnpm --filter @agentspec/codegen        test
 pnpm --filter @agentspec/sidecar      test
 
 # Sidecar — unit/integration + E2E (needs Docker)
@@ -71,7 +71,7 @@ When running `agentspec generate` locally:
 
 | Variable | Required | Default | Purpose |
 |----------|----------|---------|---------|
-| `ANTHROPIC_API_KEY` | Yes (for generate/helm) | — | Claude API key |
+| `ANTHROPIC_API_KEY` | Yes (for generate/helm) | — | Anthropic API key |
 | `ANTHROPIC_MODEL` | No | `claude-opus-4-6` | Override model |
 | `ANTHROPIC_BASE_URL` | No | Anthropic API | Custom proxy endpoint |
 
@@ -92,19 +92,19 @@ When running the sidecar locally (or in tests):
 agentspec/
 ├── packages/
 │   ├── sdk/              @agentspec/sdk        — manifest schema, health checks, audit rules
-│   ├── adapter-claude/   @agentspec/adapter-claude — LLM code generation via Claude API
+│   ├── codegen/          @agentspec/codegen        — Provider-agnostic LLM code generation
 │   ├── cli/              @agentspec/cli        — agentspec CLI binary
 │   └── sidecar/          @agentspec/sidecar    — Fastify proxy + control plane
 ├── docs/                 VitePress docs site
 ├── schemas/v1/           JSON Schema (generated, do not hand-edit)
 └── Makefile              Top-level convenience targets
 ```
 
-**Build order matters:** `sdk` must be built before `adapter-claude` and `cli`, because they depend on it as workspace packages.
+**Build order matters:** `sdk` must be built before `codegen` and `cli`, because they depend on it as workspace packages.
 
-## Adapter Build Note
+## Codegen Build Note
 
-`@agentspec/adapter-claude` build script copies skill Markdown files to `dist/skills/`:
+`@agentspec/codegen` build script copies skill Markdown files to `dist/skills/`:
 ```bash
 tsup && mkdir -p dist/skills && cp src/skills/*.md dist/skills/
 ```

docs/adapters/autogen.md

@@ -5,11 +5,10 @@ Generate Python AutoGen agent code from your `agent.yaml` manifest.
 ## Usage
 
 ```bash
-export ANTHROPIC_API_KEY=your-api-key-here
 agentspec generate agent.yaml --framework autogen --output ./generated/
 ```
 
-Get an API key at [console.anthropic.com](https://console.anthropic.com).
+AgentSpec auto-detects your codegen provider (Claude CLI, Anthropic API, or any OpenAI-compatible endpoint). See [Provider Authentication](../guides/provider-auth) for setup.
 
 ## Generated Files
 

docs/adapters/crewai.md

@@ -5,11 +5,10 @@ Generate Python CrewAI agent code from your `agent.yaml` manifest.
 ## Usage
 
 ```bash
-export ANTHROPIC_API_KEY=your-api-key-here
 agentspec generate agent.yaml --framework crewai --output ./generated/
 ```
 
-Get an API key at [console.anthropic.com](https://console.anthropic.com).
+AgentSpec auto-detects your codegen provider (Claude CLI, Anthropic API, or any OpenAI-compatible endpoint). See [Provider Authentication](../guides/provider-auth) for setup.
 
 ## Generated Files
 

docs/adapters/langgraph.md

@@ -5,11 +5,10 @@ Generate Python LangGraph agent code from your `agent.yaml` manifest.
 ## Usage
 
 ```bash
-export ANTHROPIC_API_KEY=your-api-key-here
 agentspec generate agent.yaml --framework langgraph --output ./generated/
 ```
 
-Get an API key at [console.anthropic.com](https://console.anthropic.com).
+AgentSpec auto-detects your codegen provider (Claude CLI, Anthropic API, or any OpenAI-compatible endpoint). See [Provider Authentication](../guides/provider-auth) for setup.
 
 ## Generated Files
 

docs/adapters/mastra.md

@@ -5,11 +5,10 @@ Generate TypeScript Mastra agent code from your `agent.yaml` manifest.
 ## Usage
 
 ```bash
-export ANTHROPIC_API_KEY=your-api-key-here
 agentspec generate agent.yaml --framework mastra --output ./generated/
 ```
 
-Get an API key at [console.anthropic.com](https://console.anthropic.com).
+AgentSpec auto-detects your codegen provider (Claude CLI, Anthropic API, or any OpenAI-compatible endpoint). See [Provider Authentication](../guides/provider-auth) for setup.
 
 ## Generated Files