Developer Tooling

Foundry is built with an AI-assisted development workflow. This page documents the tools and how to set them up.

Claude Code

Claude Code is the primary development environment. It provides an AI coding agent that understands the full project context through .claude/ configuration files.

Project Configuration

The root AGENTS.md is the canonical source of truth. .claude/CLAUDE.md is a symlink to it. This enables any AI agent (Claude Code, Cursor, Windsurf) to read the same instructions.

Rules

Rules in .agents/rules/ (symlinked at .claude/rules/) encode project conventions so the AI agent follows them automatically:

• architecture.md -- System boundaries and integration points
• conventions.md -- Naming, component rules, code patterns
• decisions.md -- Boundary decisions and decision framework
• anti-patterns.md -- What to never do, red flags, values filter
• layer-development.md -- Layer-specific rules (loaded only when working in layer/)
• example-apps.md -- Example app rules (loaded only when working in examples/)

Custom Subagents

Custom subagents in .claude/agents/ handle specialized tasks:

Module-Level Documentation

Each layer module has its own AGENTS.md with file maps, architecture decisions, and modification guides. These are only loaded when the agent works on files in that module:

• layer/modules/events/AGENTS.md
• layer/modules/rss/AGENTS.md
• layer/modules/changelog/AGENTS.md
• layer/modules/docs/AGENTS.md

Environment Tuning

Key settings in .claude/settings.json:

• Compaction at 80% (CLAUDE_CODE_AUTOCOMPACT_PCT_OVERRIDE=80) -- triggers context compaction earlier for higher-quality summaries
• Auto-lint hook -- lints .vue, .ts, .js files after every edit
• Compact re-injection hook -- re-injects critical project rules after context compaction
• Visual test logging hook -- logs every agent-browser command to .claude/visual-test-log.md for observability

Agent Skills

Agent skills give the AI coding agent specialized knowledge about libraries and frameworks. Foundry uses both external community skills and custom project skills.

External Skills

External skills are defined in .claude/skills.json and installed on demand:

bash scripts/install-skills.sh

Custom Skills

Custom skills live in .claude/skills/ and are tracked in git. Foundry includes:

• docs-writer -- Documentation writing skill for Nuxt Content MDC files, with reference files for MDC syntax, components, writing patterns, and template-specific features
• visual-tester -- UI/UX visual bug detection using agent-browser annotated snapshots. See Agent Configurations for usage

Custom skills follow the Agent Skills specification with progressive disclosure: a main SKILL.md for core instructions and a references/ directory for detailed specifications loaded on demand.

VibeKanban

VibeKanban provides project and task management integrated with the AI coding workflow. It connects issues, workspaces, and repositories.

How It Works

1. Issues track work items with priority, status, tags, and assignees
2. Workspaces link issues to git branches and coding sessions
3. Sessions launch AI agents (Claude Code, Cursor, etc.) to work on issues

VibeKanban is available as an MCP server, which means AI agents can read and update issues directly during a coding session.

Typical Workflow

1. Create an issue in VibeKanban describing the task
2. Start a workspace session linked to the issue
3. The AI agent reads the issue context and begins work
4. Progress is tracked through issue status updates
5. Work is committed to the linked branch

For detailed agent configuration profiles (Manager, Implementer, Reviewer, Debugger, Browser Tester, etc.), see Agent Configurations.

Alternative Setups

The tooling described here is what the Foundry team uses. The codebase itself is framework-agnostic in its development approach:

• AI agent -- Claude Code is primary, but the .claude/ configuration patterns work with Cursor, Windsurf, or other agent-capable editors
• Project management -- VibeKanban integrates with Claude Code via MCP, but any issue tracker works
• Skills -- The skills manifest is Claude Code specific, but the reference documents in .claude/skills/ are useful context for any AI assistant

Setting Up the Workflow

1. Install Claude Code
2. Install agent skills: bash scripts/install-skills.sh
3. Review AGENTS.md (root) for project conventions
4. (Optional) Set up VibeKanban for project management
5. (Optional) Configure Agent Profiles in VibeKanban for multi-agent workflow

Rules, subagents, and hooks load automatically when Claude Code opens the project. No additional configuration is needed beyond agent skills installation.