GitHub Repository for AI Tooling
Great engineering, augmented by AI.
An opinionated, GitHub-native foundation for AI-augmented software engineering.
GRAIT provides reusable agent instructions, skills, tooling configurations, and automated workflows to bring consistency, quality, and engineering discipline to AI-assisted software development.
GitHub-native. Language-agnostic. Opinionated by design.
Start with the installation and configuration guide: new repository, existing repository, upgrade, or someone else's repository.
AI can accelerate software development, but faster code generation does not automatically produce better software.
Good software engineering still requires sound architecture, clear requirements, maintainable code, automated testing, security, and thoughtful technical decisions.
GRAIT is built around a few principles:
- Engineering fundamentals come first. Established computer science and software engineering principles apply regardless of whether code is written by humans or generated by AI.
- AI augments, humans own. AI agents assist with implementation, analysis, reviews, and automation. Humans remain accountable for decisions and outcomes.
- Simplicity over complexity. Prefer pragmatic, maintainable solutions over unnecessary abstractions, premature optimization, and overengineering.
- Quality is built in. Testing, security, observability, and maintainability are part of the development process, not afterthoughts.
- Automate what makes sense. Use deterministic automation for predictable tasks and AI-powered workflows where reasoning adds value.
- Conventions over repeated decisions. Establish sensible defaults to reduce repetitive setup and improve consistency across repositories.
Your local Codex CLI, Claude Code, or GitHub Copilot CLI session acts as the orchestrator and delegates specialists in worktrees on your machine or your own remote host. Changes are pushed to GitHub PRs; humans approve, merge, and release.
Install Git, Node.js 24 with npm, GitHub CLI, and Codex CLI, Claude Code, or GitHub Copilot CLI. Sign in to GitHub with gh auth login, then run from your clone:
npm run setup -- --plan
npm run setupSetup guides native harness login and the two GitHub App approvals, creates or reuses a Project, preserves application ownership rules, installs native roles, and prepares a configuration PR for your target repository. The App keys stay in private Git metadata on your host.
Choose Claude with npm run setup -- --harness claude or Copilot with npm run setup -- --harness copilot; Codex is the default. Follow installation and activation to complete setup and start the orchestrator. The guide also covers administrator access, existing identities, remote hosts, and interrupted setup.
| Component | Purpose |
|---|---|
| Orchestrator and specialists | Native Codex/Claude/Copilot roles for coordination, triage, testing, implementation, review, and fixes |
| Shared engineering policy | Language-neutral conventions, scoped changes, and human authority |
| Project workflow | Backlog → Ready → In Progress → Review → Done, native blockers, and at most five active stories |
| Worktrees and tester-first delivery | Separate orchestrator checkout, sequential tester/implementer ownership, independent validation |
| PR review | Separate publishing identity, inline findings, formal decisions, and bounded fix loops |
| Deterministic CI | Configuration, generated-adapter drift, tests, formatting, and Markdown checks |
| Operator releases | Optional deterministic release workflow with human approval |
Use the official harness with your own eligible subscription. Native sub-agents share its usage allowance; the default is two concurrent workers. GRAIT does not request provider API keys, run AI agents in GitHub Actions, or supply a separate LLM service. Model inference still uses the provider's servers. See subscription setup.
GitHub Apps identify who publishes, independently of where agents execute. One writer App pushes branches and opens PRs; one reviewer App publishes reviews. Tester and implementer do not need separate GitHub accounts. Neither App receives permission to bypass human merge gates.
Use GRAIT as a GitHub repository template to create a new repository, or incorporate its configuration files into an existing project.
Before using the configurations, review:
- Agent instructions and engineering conventions
- Model selection and agent permissions
- Available skills and specialized agents
- Local harness roles and deterministic GitHub Actions
- Host-side publishing credentials, Project access, and required GitHub permissions
GRAIT provides the common foundation. Extend it with project-specific context, including:
- Technology stack and architecture
- Project-specific coding standards
- Build and test commands
- Deployment and infrastructure requirements
- Domain-specific constraints
Use your configured coding agents and GitHub workflows to develop software while maintaining established engineering standards.
Follow GRAIT development when changing the starter tooling, including inside an adopting project. GRAIT's automation uses Node.js 24; your application may use any language. Edit canonical roles under automation/, then run:
npm ci
npm run harness:generate
npm run check
npm test
npm run format:check
npm run lint:mdRead setup for configuration, operations for commands and recovery, and CONTRIBUTING.md for changes. Existing installations should follow the migration guide before enabling the local orchestrator.
Technology stack: Agnostic by design.
GRAIT does not prescribe programming languages, frameworks, application architectures, or infrastructure platforms.
Repository platform: GitHub.
GRAIT intentionally relies on GitHub-native capabilities, including GitHub Actions for deterministic CI, plus issues, Projects, PRs, and reviews.
Coding agents: Initially optimized for OpenAI Codex.
Claude Code and GitHub Copilot CLI are also selectable local harnesses and have matching skill and agent adapters, sharing the same engineering principles and workflow policies.
GRAIT is not:
- An application boilerplate or framework starter.
- A replacement for engineering judgment or architectural decisions.
- A guarantee that AI-generated code is correct, secure, or production-ready.
- A universal configuration that should be applied without reviewing project requirements.
GRAIT provides an opinionated foundation, not a substitute for understanding the system you're building.
AI changes how we write software. It does not invalidate the principles of good software engineering.
Contributions, suggestions, and discussions are welcome.
Changes should align with GRAIT's core philosophy: pragmatic engineering, minimal unnecessary complexity, clear conventions, and responsible AI augmentation.
See LICENSE for details.