Skip to content

About

Bootstrap a project for AI-assisted dev across Claude Code, OpenAI Codex, and GitHub Copilot from one AGENTS.md

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

39 Commits

Folders and files

Repository files navigation

ai-dev-kit

One AGENTS.md configures Claude Code (Claude), OpenAI Codex (GPT), and the GitHub Copilot cloud agent for a project — shared standards, native slash commands, and three default methodology tools: Superpowers (workflow), ponytail (minimal code), OpenSpec (spec layer). The agent CLIs you use are assumed already installed (the script verifies them; it installs the methodology tools).

Install

Run inside the project you want to configure:

# Default — prompts you through which agents to enable
curl -fsSL https://raw.githubusercontent.com/sirinsoftware/ai-dev-kit/main/bootstrap.sh | bash

# Default + all optional extras (graphify code graph, Claude guardrail + process hooks)
curl -fsSL https://raw.githubusercontent.com/sirinsoftware/ai-dev-kit/main/bootstrap.sh \
  | bash -s -- --with-all-extras

# No curl? Same via wget
wget -qO- https://raw.githubusercontent.com/sirinsoftware/ai-dev-kit/main/bootstrap.sh | bash
wget -qO- https://raw.githubusercontent.com/sirinsoftware/ai-dev-kit/main/bootstrap.sh \
  | bash -s -- --with-all-extras

Non-interactive: append bash -s -- --yes --agents=claude,codex,copilot. All flags: ./setup.sh --help.

Edit after install

Everything you customize lives in one file — AGENTS.md. Fill in every {{…}} — or run /fill-agents to have your agent infer them from the repo's code, git history, and config (best-guess; review the git diff after). All three agents read it. This is where your code standards, check tools, and PR/commit formats go:

What you set Section in AGENTS.md Placeholder(s)
Project overview / tech stack top {{PROJECT_OVERVIEW}}, {{TECH_STACK}}
Code standards + formatter Standards → Code {{CODE_STANDARDS}}, {{FORMAT_COMMAND}}
Commit message format Standards → Commit messages {{COMMIT_STANDARDS}}
PR rules + description format Standards → Pull requests {{PR_STANDARDS}}, {{PR_DESCRIPTION_FORMAT}}
Code-review rubric (priorities, severity, merge gates) Standards → Code review {{REVIEW_STANDARDS}}, {{REVIEW_MERGE_GATES}}
Code-check tools (lint/type/security) Standards → Static analysis {{LINT_COMMAND}}, {{TYPECHECK_COMMAND}}, {{SECURITY_SCAN_COMMAND}}
Test command + coverage target Standards → Tests {{TEST_COMMAND}}, {{COVERAGE_TARGET}}
Real device / environment Standards → Real device {{REAL_DEVICE_NOTES}}, {{REAL_DEVICE_TEST_SCRIPT}}, {{REAL_DEVICE_PREREQS}}
Extra guardrails Guardrails {{EXTRA_GUARDRAILS}}

Only edit one other file — and only if you use the Copilot cloud agent: .github/workflows/copilot-setup-steps.yml — replace the TODO with your real toolchain + the lint/test installs, then commit it to the default branch.

Share vs. local — .gitignore. Your agent config (AGENTS.md, .claude/, .codex/, .github/, openspec/, slash commands) is committed by default, so the whole team shares one setup. Keep *.local.*, .claude/settings.local.json, *.adk-bak, .ai-dev-kit-manifest, and .ai-dev-kit-config ignored — those are personal/local. (With graphify enabled, the graph is ignored too; to share it instead, remove its line from the managed block and git add -f graphify-out/ — tracked files override .gitignore and survive re-runs.)

Everything else is generated and managed for you — leave it alone: CLAUDE.md, .claude/, .codex/config.toml, .github/copilot-instructions.md, and the slash-command files.

Then

  1. Codex: open the project once and trust it (so .codex/config.toml loads); restart Codex to load the /prompts:* commands.
  2. Copilot: pick the model in the task model-picker.
  3. Restart your agents so the OpenSpec + ponytail skills load.

The three default tools

Tool Owns Example
OpenSpec What to build — proposal, specs, design, tasks; validated + archived on disk /openspec-propose "reset password" → review → APPROVED.md
Superpowers How it gets built — brainstorm → plan → failing-test-first → review "Add feature X" → it plans + writes tests first
ponytail How little gets built — YAGNI, stdlib/native first, shortest diff "Add a date picker" → <input type="date">

Routing (baked into AGENTS.md): work touching 3+ files, a schema, or a shared API gets an OpenSpec change; smaller work uses Superpowers alone. OpenSpec owns proposal/design/archive (no duplicate design docs or task lists), Superpowers owns execution (worktree per change, TDD), ponytail rules apply throughout. Archive the change last. openspec validate runs as a CI check on spec changes.

/openspec-propose "user can reset password by email"    # spec: proposal + design + tasks
# review it, then create openspec/changes/<id>/APPROVED.md
/openspec-apply-change                                  # TDD implementation from tasks.md
/verify-feature <id>                                    # reviews ∥ tests ∥ device ∥ docs
/openspec-archive-change                                # fold the change into the specs

(Codex invokes OpenSpec skills as $openspec-propose etc.; Claude/Copilot use /openspec-….) Guides scaffolded into your project: docs/guides/develop-a-feature.md · docs/guides/test-a-feature.md.

Superpowers skills (the workflow it enforces)

In Claude Code these run as skills, roughly in order; Codex/Copilot follow the same flow via AGENTS.md.

Skill Activates Does
brainstorming before writing code refines a rough idea through questions, explores alternatives, presents the design for validation (for an OpenSpec change, the proposal/design docs take this role)
using-git-worktrees after design approval creates an isolated workspace on a new branch, runs project setup, verifies a clean test baseline
writing-plans with an approved design breaks work into bite-sized tasks (for an OpenSpec change, tasks.md already is the plan)
subagent-driven-development / executing-plans with a plan dispatches a fresh subagent per task with two-stage review, or executes in batches with human checkpoints
test-driven-development during implementation enforces RED → GREEN → REFACTOR; deletes code written before its test
requesting-code-review between tasks reviews against the plan and reports issues by severity — critical issues block progress
finishing-a-development-branch when tasks complete verifies tests, presents options (merge / PR / keep / discard), cleans up the worktree

ponytail

  • /ponytail toggle lazy mode (/ponytail ultra for max) · /ponytail-review a diff · /ponytail-audit the repo
  • in-mode: "add a date picker" → <input type="date">, not a library

Optional extras

Opt-in flags (--with-all-extras enables all three; interactive setup asks, defaulting to no):

Extra Does Cost / notes Flag
graphify Queryable code knowledge graph: graphify query "how does auth work", path, explain Python/uv dependency; rebuild after code changes (graphify update .); graph is gitignored --with-graphify
Claude guardrail hooks Deny secret-file reads + dangerous shell (cat .env, rm -rf /) — deterministic, Claude only none --with-hooks
Process hooks Block production edits while the branch's OpenSpec change lacks APPROVED.md; refuse to stop on a red build (ADK_PROCESS_OFF=1 bypass) Claude only --with-process-hooks

A project bootstrapped by an older kit version with graphify keeps it: setup and update.sh detect the existing graph and record it as enabled instead of removing it.

Example prompt — a feature end to end

Implement rate limiting for our HTTP API. Follow our workflow — don't jump straight to code.
1. Spec: /openspec-propose "per-client rate limiting on the public API" — requirements
   with WHEN/THEN scenarios, a design that names the algorithm + storage, tasks.
2. Stop so I can review; I'll create APPROVED.md in the change folder.
3. Implement: /openspec-apply-change — failing test first per task, minimal code
   (ponytail), worktree on a branch named after the change id.
4. Verify: /verify-feature — reviews, tests, device run, docs; commit message + PR
   description written but nothing committed or pushed.
5. I'll merge; then /openspec-archive-change.

Reference

  • Slash commands (where enabled): /pr-review, /deep-test, /security-audit (no API key), /progress-report, /repeatable-task, /report-html, /fill-agents (fill AGENTS.md from the repo), /update-tools, /review-fresh, /verify-feature. Codex uses /prompts:<name>.
  • HTML reports/plans: ask any report/plan command for HTML — or run /report-html <topic|file> — for a styled, self-contained .html (Catppuccin Mocha) under docs/reports/. The house style lives in AGENTS.md → Output formats.
  • Options & conflict handling: ./setup.sh --help. Re-running is safe (idempotent; tracked in .ai-dev-kit-manifest); AGENTS.md is never overwritten.
  • Update tools: ~/.ai-dev-kit/update.sh . (or /update-tools) — upgrades the OpenSpec CLI + project skills, upgrades graphify/rebuilds the graph where enabled, and cleans up anything an older kit version left (retired commands, old MCP entries). Add --dry-run to preview.
  • Uninstall: ~/.ai-dev-kit/uninstall.sh . (add --dry-run to preview) — restores backups, removes only kit files, strips kit .gitignore/hook entries; your openspec/ specs are never touched.
  • Docs: how each agent reads its config · design · tool catalog · QA test plan.

About

Bootstrap a project for AI-assisted dev across Claude Code, OpenAI Codex, and GitHub Copilot from one AGENTS.md

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages