AI-Assisted Development Setup

January 12, 2026 · View on GitHub

This repository contains an experiment in structuring AI-assisted development workflow, designed to help teams adopt Claude Code with enterprise-grade best practices.

What This Repository Does

This repo packages and distributes a complete setup for AI-assisted software development, including:

  • CLAUDE.md - Project guidelines and SDLC workflow instructions for Claude Code
  • Specialized Agents - Six purpose-built agents for different phases of development
  • Workflow Automation - Git hooks, CI/CD pipelines, and release automation

Teams can download a single zip file and extract it into their project to instantly get:

  • Structured SDLC phases (Requirements → Planning → Development → Testing)
  • Trunk-based development workflow with proper git management
  • Consistent commit patterns and PR workflows
  • Specialized agents that guide developers through each phase

For End Users

If you're looking to use this setup in your project (not develop it), see README-CLAUDE-CODE.md for installation instructions.

Quick start:

# Install Claude Code (if not already installed)
# npm install -g claude

# Download the latest release
curl -L https://github.com/jarombouts/gapstars-coding-agents/releases/latest/download/gapstars-ai-setup.zip -o gapstars-ai-setup.zip

# Extract in your project root
unzip gapstars-ai-setup.zip

# Start Claude Code
claude

The rest of this file is written for people who want to understand this repo containing the agent templates, not use it.

Repository Structure

.
├── CLAUDE.md                      # Main instructions for Claude Code (copied to projects)
├── README-CLAUDE-CODE.md          # User-facing setup guide (copied to projects)
├── DEPLOYMENT.md                  # How to create releases and manage this repo
├── .claude/                       # Agent definitions and settings (copied to projects)
│   ├── agents/                    # Six specialized agent definitions
│   │   ├── requirements-and-specs.md
│   │   ├── plan-work.md
│   │   ├── execute-development.md
│   │   ├── test-development.md
│   │   ├── git-workflow-manager.md
│   │   └── ai-readiness-interrogator.md
│   ├── PROJECT_CONTEXT.md         # Template for project state tracking
│   └── settings.local.json        # Claude Code settings
├── scripts/                       # Build and release automation
│   ├── package.sh                 # Creates versioned zip artifact
│   └── tag-release.sh             # Helper to create and push version tags
└── .github/workflows/
    └── release.yml                # GitHub Actions workflow for releases

How the Packaging System Works

Overview

When you push a version tag (e.g., v1.0.0), GitHub Actions automatically:

  1. Runs scripts/package.sh to create a versioned zip
  2. Creates a GitHub Release with auto-generated notes
  3. Uploads the zip artifact to the release
  4. Provides a stable download URL

The Release Flow

Developer                Git                    GitHub Actions           Users
    |                    |                           |                     |
    |-- Edit files --→   |                           |                     |
    |                    |                           |                     |
    |-- Run: ./scripts/tag-release.sh patch          |                     |
    |                    |                           |                     |
    |                    |-- Push tag v1.0.1 --→     |                     |
    |                    |                           |                     |
    |                    |                      Trigger workflow           |
    |                    |                           |                     |
    |                    |                      Run package.sh             |
    |                    |                           |                     |
    |                    |                      Create Release             |
    |                    |                           |                     |
    |                    |                      Upload zip artifact        |
    |                    |                           |                     |
    |                    |                           |-- Publish --→       |
    |                    |                           |                     |
    |                    |                           |         curl/download zip

Creating a Release

Simple method (recommended):

# Patch release (0.0.X) - bug fixes, small updates
./scripts/tag-release.sh patch

# Minor release (0.X.0) - new features, new agents
./scripts/tag-release.sh minor

# Major release (X.0.0) - breaking changes
./scripts/tag-release.sh major

The script will:

  1. Calculate the next version number from existing tags
  2. Create an annotated git tag
  3. Push the tag to GitHub
  4. Trigger the GitHub Actions workflow
  5. Show you the download URLs

Download URLs

Once released, users can download at:

Latest version (always current):

https://github.com/jarombouts/gapstars-coding-agents/releases/latest/download/gapstars-ai-setup.zip

Specific version:

https://github.com/jarombouts/gapstars-coding-agents/releases/download/v1.0.0/gapstars-ai-setup.zip

Package Contents

Each release includes:

  • CLAUDE.md - Workflow instructions
  • README-CLAUDE-CODE.md - Setup guide for end users
  • .claude/agents/ - All six specialized agents
  • .claude/PROJECT_CONTEXT.md - Template for project tracking
  • .claude/settings.local.json - Claude Code settings
  • VERSION - Build metadata (version, date, commit hash)

Versioning Strategy

We follow Semantic Versioning:

  • MAJOR (X.0.0): Breaking changes to workflow structure or agent interfaces
  • MINOR (0.X.0): New agents, significant features, workflow improvements
  • PATCH (0.0.X): Bug fixes, documentation updates, small tweaks

The Six Specialized Agents

1. Requirements & Specs (requirements-and-specs.md)

  • Gathers business context through socratic dialogue
  • Creates detailed technical specifications
  • Bridges gap between business needs and technical implementation

2. Plan Work (plan-work.md)

  • Designs solution architecture
  • Creates detailed implementation plans
  • Breaks work into manageable development phases

3. Execute Development (execute-development.md)

  • "Blue Team" approach - builds the happy path
  • Iterative implementation following plans
  • Collaborative problem-solving

4. Test Development (test-development.md)

  • "Red Team" approach - finds failure modes
  • Critical review and edge case testing
  • Advises on code acceptance

5. Git Workflow Manager (git-workflow-manager.md)

  • Manages branches and commits throughout SDLC
  • Ensures frequent, small commits
  • Handles PR creation and merge workflows

6. AI Readiness Interrogator (ai-readiness-interrogator.md)

  • Cuts through vague AI feature requests
  • Uses socratic questioning to extract real requirements
  • Generates concrete job profiles from buzzword soup

Development Workflow (For This Repo)

Working on New Agents or Features

Use git worktrees for parallel development:

# Create a worktree for a new feature
git worktree add ../gapstars-upskilling-worktrees/new-agent -b feature/new-agent

# Work in the worktree
cd ../gapstars-upskilling-worktrees/new-agent

# When done, commit and push
git push -u origin feature/new-agent

# Remove worktree after merging
git worktree remove ../gapstars-upskilling-worktrees/new-agent

Testing Changes Locally

Before releasing, test the package locally:

# Build the package
./scripts/package.sh

# Inspect contents
unzip -l gapstars-ai-setup-*.zip

# Test extraction
mkdir /tmp/test-setup
cd /tmp/test-setup
unzip ~/path/to/gapstars-ai-setup-*.zip

Release Process

  1. Make your changes
  2. Commit to master
  3. Run ./scripts/tag-release.sh patch|minor|major
  4. Wait ~30 seconds for GitHub Actions to complete
  5. Verify release at: https://github.com/jarombouts/gapstars-coding-agents/releases

Contributing

  1. Fork the repository
  2. Create a feature branch or worktree
  3. Make your changes
  4. Test locally with ./scripts/package.sh
  5. Submit a PR to master
  6. After merge, maintainers will create a new release

License

[Add your license here]

Questions?