# AGENTS.md

## What This Project Is
[Tool name] is a [one-sentence mental model]. [One sentence about
how the tool is structured — schema-first? config-driven? convention-based?]

## Before You Do Anything
You cannot do useful work without knowing [context variable] and [task].
Present this prompt to the human:

---

I've loaded the [tool name] project. To help you, I need:

1. **[Context question]?** (pick one or describe a new one)
   Available options: [list explicitly]

2. **What do you want to do?**
   - [Task 1] (`command-name`)
   - [Task 2] (`command-name`)
   - [Task 3] (`command-name`)
   - Something else?

---

## Key Rules
- [Rule that prevents data corruption or build breakage]
- [Rule about human approval gates]
- [Rule about format constraints]
- Read CLAUDE.md for full project rules.

# AGENTS.md

## What This Project Is
Brand-forge is a CLI-first design toolkit. One JSON schema (the Brand Kit)
defines a brand's colors, typography, voice, and spacing. Exporters turn
that schema into CSS, Tailwind, Figma tokens, and media assets. Generators
use AI to propose creative options that humans approve.

## Before You Do Anything
You cannot do useful work without knowing which brand and what task.
Present this prompt to the human:

---

I've loaded the brand-forge project. To help you, I need:

1. **Which brand kit?** (pick one or tell me a new brand name)
   Available presets: 630volleyball, flickday, letspepper,
   signal-dispatch, volley-rx

2. **What do you want to do?**
   - Create a new brand from scratch (`init`)
   - Generate creative proposals — palette, fonts, voice (`generate`)
   - Export to a format — CSS, Tailwind, Figma, Markdown (`export`)
   - Render media — social card, flyer, favicon (`media`)
   - Full asset package (`batch`)
   - Review/validate an existing kit (`review`)
   - Something else?

---

## Key Rules
- Exporters are pure functions. No AI, no network, no randomness.
- Generators propose. Humans approve. Never auto-apply.
- All colors are #rrggbb. No shorthand, no rgb(), no named colors.
- Review gates must pass before export.
- Read CLAUDE.md for full project rules.

# CLAUDE.md

## Module Boundaries
- `src/[module-a]/` — [What it does]. [What it must NOT do].
- `src/[module-b]/` — [What it does]. [Constraints].
- `src/[module-c]/` — [What it does]. Source of truth for [schema/config].

## Pre-Commit Checklist
1. `[lint command]` passes
2. `[test command]` passes
3. [Validation specific to your tool]
4. No `any` types introduced

## Rules
1. [Hard constraint about purity/side effects]
2. [Hard constraint about human approval gates]
3. [Hard constraint about schema/format]
4. [Hard constraint about file conventions]
5. Don't modify [protected files/directories] unless explicitly asked.

# CLAUDE.md

## Module Boundaries
- `src/generators/` — AI proposals. Always async. Always interactive.
- `src/exporters/` — Pure functions. NO AI. NO network. NO randomness.
- `src/extractors/` — Regex-based parsing. NO AI. NO prompts.
- `src/schema/` — Zod validation. Source of truth for BrandKit shape.
- `src/media/` — Satori JSX → SVG → PNG rendering.

## Pre-Commit Checklist
1. `npm run lint` passes
2. All five presets parse: `npm run dev -- review --kit presets/*.json`
3. No `any` types introduced
4. All imports use `.js` extension (ESM-only)

## Rules
1. Exporters are pure. Same input → same output. Always.
2. Generators propose via interactive prompt. Never auto-apply results.
3. Schema changes cascade — update ALL presets and run ALL tests.
4. Every color value is #rrggbb (6-digit hex, lowercase).
5. Every preset must pass both parseBrandKit() and reviewBrandKit().
6. Don't modify presets/ files unless explicitly asked.

// src/commands/agent-prompt.ts

import { parseBrandKit } from '../schema/brand-kit.js';
import { EXPORT_FORMATS } from '../exporters/index.js';
import { readFileSync } from 'node:fs';

export async function agentPrompt(kitPath: string, task: string) {
  const raw = JSON.parse(readFileSync(kitPath, 'utf-8'));
  const kit = parseBrandKit(raw); // Same validation as the real CLI

  const brandSummary = [
    `- **Name**: ${kit.meta.name}`,
    `- **Theme**: ${kit.colors.mode}`,
    `- **Primary**: ${kit.colors.primary}`,
    `- **Font Display**: ${kit.typography.display.family}`,
    `- **Font Body**: ${kit.typography.body.family}`,
  ].join('\n');

  const formats = Object.keys(EXPORT_FORMATS)
    .map(f => `- \`export ${f}\` — ${EXPORT_FORMATS[f].description}`)
    .join('\n');

  const commands = task === 'export'
    ? Object.keys(EXPORT_FORMATS)
        .map(f => `npm run dev -- export ${f} --kit ${kitPath}`)
        .join('\n')
    : `npm run dev -- ${task} --kit ${kitPath}`;

  return `## Context
You are working with brand-forge on the "${kit.meta.name}" brand kit.

### Brand Summary
${brandSummary}

### Available ${task === 'export' ? 'Export Formats' : 'Commands'}
${formats}

### Constraints
- Exporters are pure functions. No AI or network calls.
- All color values must be #rrggbb format.
- Run review after any changes to verify the kit passes validation.

### Commands
\`\`\`
${commands}
\`\`\`

### Validation
\`\`\`
npm run dev -- review --kit ${kitPath}
\`\`\``;
}

#!/usr/bin/env bash
# agent-prompt.sh — Generate a structured prompt for AI agents
# Usage: ./agent-prompt.sh <config-file> <task>

set -euo pipefail

CONFIG="$1"
TASK="${2:-help}"

if [ ! -f "$CONFIG" ]; then
  echo "Config not found: $CONFIG"
  echo "Available configs:"
  ls configs/ 2>/dev/null || echo "  (no configs/ directory)"
  exit 1
fi

# Extract key fields from your config (adapt to your format)
NAME=$(grep -m1 '"name"' "$CONFIG" | sed 's/.*: *"\(.*\)".*/\1/')

# List available commands from --help or a known set
COMMANDS=$(your-tool --help 2>&1 | grep '^\s\s' | head -10)

cat <<EOF
## Context
You are working with [your-tool] on the "${NAME}" configuration.

### Available Commands
${COMMANDS}

### Constraints
- [Your key rules here]
- Run \`your-tool validate --config ${CONFIG}\` after any changes.

### Validation
\`\`\`
your-tool validate --config ${CONFIG}
your-tool test --config ${CONFIG}
\`\`\`
EOF