Agentive Starter Kit

A bit of structure to help you get more out of agentive software development

Using agents to build software works better if you add a bit of structure. Anthropic calls this a harness. We created the tools in this kit to overcome the usual problems of agentive development: documentation, testing, architecture, and value for money (and tokens).

When we start a new project, we clone this repo and complete the onboarding. This gives us tests, tasks, documentation, and token-efficient tools, all in about ten minutes. You can tweak things as you wish, including how the agents work, and what models you use.

---

What's inside?

1. An onboarding agent to help you get started.

2. A selection of specialized agents that have specific tasks, instructions, and tools. Some of them create and track plans, others write code, and so on.

3. A package we created called adversarial-workflow which lets agents get a "second opinion" from specialized Evaluators. Built-in evaluators handle plan review, code review, and documentation proofreading. You can also create custom evaluators for security audits, performance analysis, and more. We found that constructive critique among agents gives a big productivity boost.

4. A task management setup with task templates, a task tracking system, and an optional Linear sync.

5. Infrastructure for test-driven development (TDD), with test templates, quality gates, pre-commit hooks, and more.

6. A system for creating and maintaining architectural decision records; think of it as a knowledgebase for agents – and humans.

7. Integration with Serena, by Oraios, for helping agents work more effectively with the codebase.

8. Detailed documentation on how to select the right agent, size tasks correctly, write good tests, and more

---

Requirements

If you'd like to try this kit, here are the tools you'll need:

To get started

Requirement	How to Check	How to Get
A Claude account	Log in to claude.ai	Sign up
Claude Code installed in your terminal or IDE	claude --version	Download or install VS Code/Cursor extension
GitHub account	Log in to github.com	Sign up
Git configured	git config user.name && git config user.email	Setup guide

New to Git? Check out GitHub's Git Handbook for a quick introduction.

To start building

Requirement	How to Check	How to Get
Python 3.10-3.12	python3 --version	python.org or brew install python@3.12
uvx or pipx	uvx --version or pipx --version	curl -LsSf https://astral.sh/uv/install.sh | sh

Evaluation and planning support

Requirement	Purpose	How to Get
OpenAI API Key	Adversarial evaluation (built-in evaluators)	platform.openai.com
Linear Integration	Task sync with Linear issues	See Linear Integration section below

Not sure if you have everythng you need?

Clone the repo and run this script to validate your environment:

.kit/launchers/preflight

It will check all requirements and tell you what's missing.

---

Quick Start

There are three ways to spin up a new project from this kit, in order of least to most manual:

• Option A — From a URL (zero setup): open Claude Code anywhere, paste the kit's URL, and ask it to set up a new project. Claude clones the kit and follows the create-project recipe itself. Best when you just want it done.
• Option B — Agent-driven (deterministic): clone the kit yourself, then explicitly invoke the create-project agent. Same end result as Option A, but you control where the kit checkout lives. Best for repeat use.
• Option C — Launcher-based: clone the kit straight into your project folder and run the onboarding launcher. Best when you're comfortable inheriting the kit's git history (or plan to re-init).

Option A — From a URL (Zero Setup)

If you have Claude Code installed, you don't need to clone anything yourself. Just open a Claude Code session in any directory and paste:

https://github.com/movito/agentive-starter-kit

Please set up a new project from this kit.

Claude will:

1. Clone the kit to a working directory (it will pick a sensible location, or ask)
2. Read .claude/agents/create-project.md and follow that recipe
3. Ask you the same questions the create-project agent asks (target directory, project name, task prefix, description, GitHub visibility, optional target codebase)
4. Run scripts/optional/create-project.sh, customize identity files, init adversarial-workflow, install evaluators, and create the GitHub repo

What you need installed beforehand:

• Claude Code (claude --version)
• git, gh (GitHub CLI, authenticated via gh auth status)
• uvx or pipx (for adversarial-workflow)

Honest caveat: this path relies on Claude reading the create-project agent file and following its instructions in the main session. It's not a deterministic shell script — if anything in the recipe changes, behavior may vary slightly between sessions. For a fully predictable run, use Option B.

Option B — Agent-Driven Setup (Deterministic)

This path uses the create-project agent to create a brand new project on GitHub from a clean export of the kit.

1. Clone the kit somewhere persistent (you'll reuse this checkout for future projects):

cd ~/Github
git clone https://github.com/movito/agentive-starter-kit.git
cd agentive-starter-kit

2. Open Claude Code in that directory and invoke the agent:

> Use the create-project agent to set up a new project for me

3. Answer the agent's questions. It will ask for:

• Target directory (e.g., ~/Github/my-new-project)
• Project name and one-sentence description
• Task prefix (2-4 uppercase letters, e.g., MNP)
• GitHub visibility (private or public)
• Optional: path to an existing codebase if this project will analyze it

4. The agent does the rest. It will:

• Run scripts/optional/create-project.sh to export a clean copy (via git archive, no kit history)
• Customize CLAUDE.md, pyproject.toml, and README.md with your project identity
• Initialize adversarial-workflow and install the default evaluator library
• Create the GitHub repo with gh repo create and push the first commit
• Print a summary with next steps (add .env, open the new project in Claude, invoke planner2)

When it finishes, cd into your new project directory and start working.

Option C — Launcher-Based Onboarding

Use this if you want to clone the kit directly as your project (you'll inherit the kit's git history unless you rm -rf .git && git init).

1. Clone the repository into your project folder:

cd ~/Github
git clone https://github.com/movito/agentive-starter-kit.git your-project-name
cd your-project-name

For example, if you're building a weather app:

git clone https://github.com/movito/agentive-starter-kit.git weather-app
cd weather-app

2. Run first-time onboarding:

.kit/launchers/onboarding

3. Follow the interactive setup. The onboarding agent will guide you through:

1. Project Configuration - Name your project
2. Language Selection - Configure Serena for your languages
3. API Keys - Set up Anthropic, OpenAI, and Linear (optional)
4. Feature Selection - Enable evaluation, task sync, etc.
5. First Task - Create your first task to get started

Important: When asked for your project name, use the same name you chose for the folder (e.g., weather-app). Onboarding uses this to configure Serena and update agent files so they can navigate your codebase.

Setup takes approximately 5-10 minutes.

---

What's Included

Agents (.claude/agents/)

Agent	Purpose
planner	Helps you plan, tracks work, keeps things on track
feature-developer	Implementation tasks
test-runner	TDD and testing
powertest-runner	Comprehensive test suites
document-reviewer	Documentation quality
security-reviewer	Security analysis
code-reviewer	Reviews implementations for quality
ci-checker	CI/CD verification
agent-creator	Create new specialized agents
create-project	Spin up a new project from this kit (clean export, GitHub repo, evaluator install)

Task Management (.kit/tasks/)

Linear-compatible folder structure:

.kit/tasks/
├── 1-backlog/      → Backlog (planned, not started)
├── 2-todo/         → Todo (ready to start)
├── 3-in-progress/  → In Progress (active work)
├── 4-in-review/    → In Review (awaiting review)
├── 5-done/         → Done (completed)
├── 6-canceled/     → Canceled
├── 7-blocked/      → Blocked (waiting on dependencies)
├── 8-archive/      → Archive (historical)
└── 9-reference/    → Reference (templates, docs)

Adversarial Evaluation (.adversarial/)

Independent AI review of your plans, code, and documentation:

# Review a task plan before implementation
adversarial evaluate .kit/tasks/2-todo/TASK-0001-my-task.md

# Review implemented code before merge
adversarial review src/feature/

# Proofread documentation
adversarial proofread docs/guide.md

# Discover all available evaluators
adversarial list-evaluators

# Install additional evaluators (Gemini, Mistral, more)
./scripts/project install-evaluators

Built-in evaluators use OpenAI. Custom evaluators can use other providers (Google, Mistral, Anthropic). Results saved to .adversarial/logs/.

Serena Integration (.serena/)

Semantic code navigation with LSP support:

• Python (pylsp)
• TypeScript/JavaScript (typescript-language-server)
• Swift (sourcekit-lsp)
• And more...

Reduces token consumption by 70-98% for code navigation tasks.

Note: When Serena is configured, your browser may briefly open with the Serena dashboard when launching agents. This is normal behavior - you can close it and continue working in your terminal.

---

Configuration

The onboarding agent handles all configuration automatically:

.kit/launchers/onboarding

This guides you through setting up:

• Project name and task prefix
• Programming languages (for Serena)
• API keys (OpenAI, Linear)
• GitHub repository
• First task creation

If you prefer to handle setup yourself, copy these template files and configure manually:

• .env.template → .env (API keys)
• .serena/project.yml.template → .serena/project.yml (languages)
• .adversarial/config.yml.template → .adversarial/config.yml (evaluation settings)

---

Linear Integration

The starter kit includes a built-in task management system that helps agents do better work and helps you track progress. Tasks are stored as markdown files in .kit/tasks/ folders.

You can optionally sync these tasks with Linear for team visibility and project management. This is more involved than just adding an API key.

Setting Up Linear (Optional)

1. Create a Linear account

Sign up at linear.app if you don't have an account.

2. Create a new team

Go to Settings → Teams → Create new team

Important: Use the same identifier for your Linear team as you use for task prefixes in the codebase. For example:

• If your task files are named ABC-0001-feature.md, ABC-0002-bugfix.md
• Set your Linear team identifier to ABC

This keeps task IDs consistent between your codebase and Linear.

3. Get your Linear API key

Go to your Linear workspace settings: https://linear.app/{workspace}/settings/account/security (Replace {workspace} with your Linear workspace name, e.g., ixda)

• Scroll down to "Personal API keys"
• Click "Create new API key"
• Give it a name (e.g., "agentive-starter-kit")
• Copy the key (starts with lin_api_)

4. Get your Team ID

Your Team ID is the identifier you chose in step 2 (e.g., ABC).

5. Configure your .env file

LINEAR_API_KEY=lin_api_your-key-here
LINEAR_TEAM_ID=ABC

How Linear Sync Works

When configured, the task system:

• Syncs task files in .kit/tasks/ folders to Linear issues
• Maps folder locations to Linear statuses (e.g., 2-todo/ → "Todo")
• Adds GitHub links to task files in Linear issue descriptions

Manual sync:

./scripts/project linearsync

Auto-sync: Pushing to main or develop triggers GitHub Actions workflow.

GitHub Actions setup:

1. Go to your repo Settings → Secrets and variables → Actions
2. Add LINEAR_API_KEY secret
3. Add LINEAR_TEAM_ID secret (optional)

Without Linear

Tasks work fine without Linear - they're just markdown files. Agents can create, track, and complete tasks using the folder structure alone. Linear adds team visibility and integrations, but isn't required.

---

Usage

First-Time Setup

# Run onboarding (first time only)
.kit/launchers/onboarding

Launching Agents (After Setup)

# Interactive menu
.kit/launchers/launch

# Launch specific agent
.kit/launchers/launch planner
.kit/launchers/launch feature-developer
.kit/launchers/launch test-runner

Creating Tasks

The easy way: Just tell planner what you want to build. The agent will create and manage tasks for you.

.kit/launchers/launch planner
# Then: "I want to add user authentication to my app"

Manual task creation (if you prefer):

1. Copy task template: .kit/tasks/9-reference/templates/task-template.md
2. Create task file: .kit/tasks/2-todo/TASK-0001-my-task.md
3. Run evaluation: adversarial evaluate .kit/tasks/2-todo/TASK-0001-my-task.md
4. Assign to agent via planner

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=your_project --cov-report=term-missing

---

Documentation

• Agentive Development Guide: docs/agentive-development/README.md
• Agent Template: .kit/templates/AGENT-TEMPLATE.md
• Task Template: .kit/tasks/9-reference/templates/task-template.md
• Evaluation Workflow: .adversarial/docs/EVALUATION-WORKFLOW.md
• Starter Kit ADRs: .kit/adr/ (18+ architectural decisions)
• Your Project ADRs: docs/adr/ (start fresh here)

---

Project Structure

your-project/
├── .adversarial/            # Evaluation config, evaluators, scripts, docs
├── .claude/
│   ├── agents/              # Implementation agents
│   ├── commands/            # Implementation commands
│   ├── skills/              # Implementation skills
│   └── settings.local.json  # Claude Code settings
├── .kit/                    # Builder layer
│   ├── templates/           # Agent and task templates
│   ├── skills/              # Builder skills (self-review, etc.)
│   ├── context/             # Agent coordination, workflows, patterns
│   ├── tasks/               # Task files (numbered folders)
│   ├── adr/                 # Kit ADRs (KIT-ADR-*)
│   ├── launchers/           # Agent launcher scripts
│   └── docs/                # Builder documentation
├── .serena/
│   └── project.yml          # Serena configuration
├── docs/
│   ├── adr/                 # Your project ADRs
│   └── prd/                 # Product Requirements Documents
├── scripts/                 # Project scripts
├── tests/                   # Test suite
├── .env                     # Environment variables (git-ignored)
├── .pre-commit-config.yaml  # Pre-commit hooks
└── pyproject.toml           # Python project config

---

Philosophy

Progressive Refinement Over Perfectionism

• Start simple, iterate based on real feedback
• 2-3 iteration maximum on any task
• Ship with known limitations

Test-Driven Development

• Tests before implementation
• 80%+ coverage for new code
• Pre-commit hooks catch issues early

Multi-Model Collaboration

• Claude for implementation
• Evaluators for independent review (plans, code, docs)
• Planner for orchestration

Context Management

• Documentation is infrastructure
• Handoffs prevent context loss
• Shared memory enables coordination

---

Four Ways to Use This Kit

From a URL (Zero Setup)

Open Claude Code anywhere, paste the kit URL, ask Claude to set up a new project. Claude clones the kit and follows the create-project recipe. See Quick Start → Option A.

Agent-Driven Project (Deterministic)

Clone the kit yourself, then explicitly invoke the create-project agent. Same end result as the URL flow, but you control where the kit checkout lives.

# In a checkout of agentive-starter-kit, open Claude Code and:
> Use the create-project agent to set up a new project for me

See Quick Start → Option B. Use this when starting new projects often and want a stable kit checkout to reuse.

Kit Project (Full Setup, Manual)

Clone the repo and run the onboarding launcher. You get everything: planning agents, evaluators, task management, Linear sync, and the full builder layer in .kit/ — but the kit's git history travels with you.

git clone https://github.com/movito/agentive-starter-kit.git my-project
cd my-project
.kit/launchers/onboarding

See Quick Start → Option C. Use this when you want full control over the setup steps or are comfortable with the kit history.

Consumer Project (Lightweight)

Bootstrap a project with just the implementation tools — agents, scripts, and commands — without the builder layer. No .kit/ directory, no planning agents, no evaluators.

# From your agentive-starter-kit checkout:
./scripts/local/bootstrap-consumer.sh ~/Github/my-app

Use this when you want agentive coding help but don't need task management or multi-agent coordination.

---

Pulling Updates from the Starter Kit

As we improve the starter kit, you can pull updates into your project:

# Add the starter kit as upstream (one time)
git remote add upstream https://github.com/movito/agentive-starter-kit.git

# Pull updates
git fetch upstream
git merge upstream/main

# Update agent files with your project name
./scripts/project reconfigure

The reconfigure command updates Serena activation calls in agent files after pulling upstream changes. It replaces any activate_project("...") value (whether it's the placeholder "your-project" or upstream's "agentive-starter-kit") with your project name from .serena/project.yml.

How merging works:

• Files only you changed → your changes preserved
• Files only upstream changed → you get the updates
• Files both changed → merge conflict (you decide what to keep)

Best practices for easy updates:

• Keep customizations in new files when possible (new agents, new docs)
• Avoid heavily editing core starter kit files
• When you do edit core files, the merge is usually straightforward

Your stuff stays safe:

• Custom agents you created
• Your .env configuration (gitignored)
• Project-specific docs and tasks

---

Contributing

This starter kit is extracted from real development practices. Contributions welcome:

1. Found a better pattern? Document what and why
2. Tried this approach? Share your results
3. Adapted for your domain? Share variations

---

License

MIT

---

Acknowledgments

Developed through real-world use on production projects. Special thanks to the Claude team and all AI provider teams for making agentive development possible.

---

Version: 0.5.0 Last Updated: 2026-03-30