Skip to content

dexter826/codebase-setup

v1.0.0MIT

Set up or harden any codebase into a working baseline with source initialization, quality gates, tests, CI, Docker/env, developer docs, and AI agent context, using consent-driven execution.

codebase-setup

codebase-setup is an Agent Skill that sets up a clean, runnable baseline for new or existing repositories: runnable source code, linting and formatting, automated tests, CI workflows, container configuration, standard documentation, and agent instructions.

It computes changes by comparing the repository's current state against the target configuration:

Target Baseline = Archetype × Stack × Depth × Modules
Current State   = evidence from repository + runtime environment
Gap             = Target − Current
Setup           = ordered, consented closure of Gap

The skill inspects existing manifests, PRDs, and chat context to generate a setup plan, then applies only the changes needed to close the gap.


Features

  • Three operating modes: scaffold for new directories, harden for existing repositories, and audit-only for non-modifying reviews.
  • Detects the project archetype (application, service, CLI, library, monorepo, or skill package) and selects appropriate tooling.
  • Verifies tool commands and options against official documentation or --help output rather than relying on static assumptions.
  • Pauses for approval before installing toolchains, global utilities, or package dependencies, and before writing initial source code.
  • Merges configurations and respects existing project conventions instead of overwriting custom files without permission.
  • Previews AGENTS.md and Google Stitch compliant DESIGN.md before creating them.
  • Provides standard templates for licenses, contributing guidelines, and security policies.
  • Validates every setup step with actual exit codes, isolating new issues from pre-existing repository errors.

Operating modes

ModeWhen to useBehavior
scaffoldTarget directory is empty or starting a new projectRuns official scaffolding tools with user approval
hardenRepository already contains code or manifestsAdds missing tooling, tests, CI, and docs without overwriting source code
audit-onlyAssessing gaps or running a repository checkInspects the workspace without writing files or installing packages

Scope matrix

AxisSupported values
Archetypeapplication, service/API, library/CLI, monorepo, skill package, docs/content, generic
StackJavaScript/TypeScript, Python, Go, other ecosystems, generic
Depthminimal, standard (default), strict
Modulesstructure, quality, tests, delivery, docs, community, design, agent context

Toolchains are discovered at runtime. The skill checks the repository, validates flags against local commands or official documentation, and logs exact references in the final setup report.


Installation

Via plugin marketplace (Claude Code, Codex, Antigravity)

Claude Code:

/plugin marketplace add dexter826/codebase-setup
/plugin install codebase-setup@codebase-setup

Codex:

codex plugin marketplace add dexter826/codebase-setup
codex plugin add codebase-setup@codebase-setup

Antigravity:

agy plugin install https://github.com/dexter826/codebase-setup

Via skills CLI

Install into current project:

npx skills add dexter826/codebase-setup

Install globally:

npx skills add dexter826/codebase-setup -g -y

Manual git installation

Copy skills/codebase-setup into your agent's skills directory. This installs the runtime payload (SKILL.md, references/, and assets/templates/) without repository overhead.

Global on Unix/macOS (~/.agents/skills):

tmp=$(mktemp -d) && git clone --depth 1 https://github.com/dexter826/codebase-setup.git "$tmp" && mkdir -p ~/.agents/skills && rm -rf ~/.agents/skills/codebase-setup && cp -R "$tmp/skills/codebase-setup" ~/.agents/skills/codebase-setup && rm -rf "$tmp"

Project-local on Unix/macOS (.agents/skills):

tmp=$(mktemp -d) && git clone --depth 1 https://github.com/dexter826/codebase-setup.git "$tmp" && mkdir -p .agents/skills && rm -rf .agents/skills/codebase-setup && cp -R "$tmp/skills/codebase-setup" .agents/skills/codebase-setup && rm -rf "$tmp"

Global on Windows PowerShell ($HOME\.agents\skills):

$tmp = Join-Path $env:TEMP "codebase-setup-repo"
Remove-Item -Recurse -Force $tmp -ErrorAction SilentlyContinue
git clone --depth 1 https://github.com/dexter826/codebase-setup.git $tmp
New-Item -ItemType Directory -Force -Path "$HOME\.agents\skills" | Out-Null
Remove-Item -Recurse -Force "$HOME\.agents\skills\codebase-setup" -ErrorAction SilentlyContinue
Copy-Item -Recurse "$tmp\skills\codebase-setup" "$HOME\.agents\skills\codebase-setup"
Remove-Item -Recurse -Force $tmp

Usage examples

The skill runs whenever you ask an agent to scaffold, configure, or standardize a repository.

Set up a new web app using React, TypeScript, and Vite with tests and GitHub Actions CI.
Harden this repository: add linting, formatting, test runners, and AGENTS.md. Do not touch existing code in src/.
This repository lacks a Dockerfile and .env.example. Add them without altering pyproject.toml.
Read the PRD in docs/ and scaffold the baseline structure, but do not implement product features yet.

Before changing any files, the skill presents a plan showing modified paths, scheduled commands, and protected areas. It prompts for confirmation on significant actions and finishes with a verification report covering every executed command.


Package structure

codebase-setup/
├── skills/codebase-setup/           # Skill runtime payload
│   ├── SKILL.md                     # Main router and orchestration workflow
│   ├── assets/templates/            # Standard templates (AGENTS.md, DESIGN.md, etc.)
│   └── references/                  # Specialized topic reference guides
├── evals/                           # Evaluation scenarios and test fixtures
├── assets/                          # Brand identity and logo suite
├── plugin.json                      # Multi-platform plugin configuration
└── README.md, CHANGELOG.md, LICENSE # Documentation and licensing

Requirements and safety

  • Compatible with coding agents that support the AgentSkills specification.
  • Requires read access to the target repository and write access to the workspace.
  • Network access is only needed when installing packages or checking online documentation.

Safety guardrails:

  • Global tools are never installed without explicit confirmation.
  • Shell profiles and system PATH remain untouched.
  • Git commits are only made when requested.
  • Secrets and tokens are excluded from reports and generated configs.

License

MIT. See LICENSE for details.