GitHub-native, Human-on-the-Loop workflows for development with Codex.
Quick start · How it works · Skills · Safety and status · Documentation
Give Codex a repeatable way to prepare context, plan work, implement changes, and return evidence. Keep plans and decisions in GitHub, rather than relying on one conversation to remember everything.
Codex works inside a defined Task. Humans set direction, decide exceptions, and retain agreement, acceptance, and merge authority. The kit supplies the Skills, instructions, templates, and helpers for that workflow; it does not replace your application, development tools, or delivery process.
Adapted from Agentic Development Kit for GitHub Copilot. This edition uses Codex Skill and role files without assuming the Copilot app's native session hierarchy or a complete autonomous runtime.
Use the root of an existing Git repository that no other agent or person is changing concurrently. You do not need to clone this kit first.
| For | Prerequisites |
|---|---|
| macOS / Linux installation | Git, Bash 3.2+, curl, find, standard Unix utilities (including GNU/BSD stat), and sha256sum or shasum |
| Windows installation | PowerShell and Git for Windows, including Git Bash and its Unix utilities |
| GitHub-based development | A GitHub remote, a Codex client with access to your project, and authenticated gh plus jq for the GitHub helpers |
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/mochan-tk/agentic-dev-kit-for-codex/main/.github/scripts/scaffold-init.sh | bashWindows PowerShell
irm https://raw.githubusercontent.com/mochan-tk/agentic-dev-kit-for-codex/main/.github/scripts/scaffold-init.ps1 | iexPublic kit acquisition needs no GitHub login; authenticated helpers are a later step. The Windows entry uses Git Bash, not WSL. It has synthetic-test coverage; native Windows installation has not been measured.
The installer resolves a source revision, validates the payload, installs it, and stages only newly installed files. It preserves existing project-owned files and refuses conflicting engine files or unsafe paths. It does not create a Git repository, commit, push, configure GitHub, or start onboarding.
To preview without changing project files or the Git index:
curl -fsSL https://raw.githubusercontent.com/mochan-tk/agentic-dev-kit-for-codex/main/.github/scripts/scaffold-init.sh | bash -s -- --dry-runThese commands execute downloaded code. Review the source before trusting it.
For a fixed revision, caller-side pipefail to detect initial download failure,
PowerShell flags, or local-source installation, see the
installation guide.
If copying or staging fails, stop and review the reported partial state; do
not assume the installer has rolled it back.
Inspect the staged changes:
git diff --cachedOther changes may already have been staged before installation. Commit only the adoption changes you have reviewed, and land them on the remote default branch through your normal approval process. Do this before onboarding makes GitHub changes.
Keep your project's existing README, AGENTS, CI, and other customizations.
If an existing AGENTS.md was preserved, explicitly connect the installed
.github/codex-instructions.md and Skills as described in the
installed workflow guide.
Its no-staging description applies to the local source engine; the external
entry above stages new files. The public installation guide distinguishes both.
Before invoking the Skill, open or select the adopter checkout in Codex—
your project, not this kit's repository. In the CLI or IDE extension,
explicitly mention the installed Skill (the
official Skill invocation guide
also documents /skills selection):
$project-onboarding
When your client does not expose that invocation, use this explicit fallback:
Read and follow .agents/skills/project-onboarding/SKILL.md in this project.
Confirm it reads the installed file, not the kit-development Skill. This is an explicit handoff, not a guarantee of automatic discovery on every client.
Onboarding inventories the project, verifies its existing commands, tunes project instructions, and prepares an evidence-bearing onboarding PR and planning handoff. It does not implement your application's next feature. Review the PR, resolve or record deferred work, and accept onboarding before moving on to ordinary development.
After the reviewed installation reaches the remote default branch, onboarding runs canonical label setup and, when you supply a goal or material, drafts phase Epic Issues for your review. Those GitHub writes are distinct from optional Ruleset setup. Choose Enable now, Create disabled, or Skip explicitly; the write choices require a reviewed profile and separate consent. Skip performs no Ruleset operation. The installer itself creates neither CI workflows nor branch protection. See the onboarding Skill.
Start with a change you can easily review. For example:
Use the installed kit workflow to add CSV export to the existing report page.
Inspect the code first. Propose the acceptance criteria, owned files,
verification commands, and Task plan. Ask me to resolve unclear requirements.
After the plan is agreed, implement and test the change, then open a PR
with the results and any remaining concerns. Leave the merge decision to me.
Review the Task, diff, and evidence—not only the final chat message. Accept, redirect, or reject the result. Use the retrospective workflow when repeated friction suggests a reusable improvement.
GitHub is the durable work record. Codex sessions carry out the work; they do not replace the Issue graph or the human decision to accept a result.
flowchart LR
A[Context and agreements] --> B[Epic and Task Issues]
B --> C[Scoped Codex work]
C --> D[Pull request and checks]
D --> E[Human acceptance]
E --> F[Retrospective]
F --> B
D -->|Needs clarification or replanning| B
This diagram describes the workflow, not a guaranteed native session tree. Use the tools actually available in the selected Codex client, or an explicit handoff based on the committed files and GitHub records.
| Responsibility | Focus |
|---|---|
| Human owner | Intent, priorities, risk decisions, agreements, acceptance, and merge |
| Project / Epic coordination | The Issue graph, dependencies, next actionable Tasks, and replanning |
| Task supervision | Scope, plan, one active writer, verification, and escalation |
| Implementation worker | One scoped change, tests, commits, and evidence for a pull request |
The three shipped role definitions provide instructions. They do not establish authenticated identities or guarantee native role selection. A GitHub Projects board is optional; the Issue graph remains authoritative.
Routine, scoped work can proceed under the agreed plan without asking a human to approve every edit. Ambiguity, high risk, scope changes, and insufficient evidence return to human judgment. Agreement and merge authority stay with the owner.
Four habits make that practical: record decisions before reporting them, verify before claiming completion, keep one writer per owned scope, and escalate rather than guess. Planned handoffs preserve the current Task, plan, and committed checkpoint; they are not automatic crash recovery.
These links show the payload installed in your project. Contributor instructions for this kit are in AGENTS.md.
| Skill | Use it to |
|---|---|
| project-onboarding | Discover the project, verify its commands, and prepare its onboarding PR |
| context-collection | Collect source material with provenance, or explicitly start builtin drafting |
| context-distillation | Propose durable requirements and decisions for human review |
| plan-management | Build Epic / Task Issues and identify actionable work |
| task-routing | Choose a suitable execution path for the bounded Task |
| session-orchestration | Coordinate supervision, implementation, replanning, and handoffs |
| verification | Check the diff, test results, and current records against acceptance criteria |
| retro | Turn supported recurring problems into reviewed improvement proposals |
Use the Skill needed for the current step; do not restart onboarding for each Task. Collected material and draft requirements are not automatically accepted project truth. Distillation and review are separate decisions.
The kit is a workflow scaffold with explicit evidence and human gates—not an autonomous service or a guarantee that generated code is correct.
| Boundary | What to expect |
|---|---|
| Existing project assets | Installation preserves project-owned content and stops on unsafe conflicts |
| Updates and recovery | Reviewed local sources support known-old engine updates and operation-scoped rollback; not automatic or whole-repository recovery |
| Governance helpers | Reads report missing evidence as non-success; setup writes require separate, explicit authority |
| Feedback and retro | Reporting is consent-gated; retrospective proposals do not approve or retire controls automatically |
| Codex compatibility | Evidence is specific to the observed client and invocation path; cross-client parity and universal automatic Skill discovery are not promised |
| Product and release | A source-first workflow kit with bounded product tests; native Windows and cross-client runtime parity remain unmeasured |
The explicit governance and worktree companions run from a reviewed kit checkout. They are not additional files installed into your project by the one-command entry. See the helper and procedure guide.
This repository has a clean product Git history and preserves the accepted predecessor's 47-file payload and installer engine. See product scope and known limitations for current behavior and evidence boundaries. Earlier acceptance, research and unfinished runtime/release work remain in the predecessor records.
| You want to… | Read |
|---|---|
| Install, select a revision, update, or recover an operation | Installation guide |
| Understand the installed instructions and workflow | Installed workflow guide and installed AGENTS |
| Understand Issue-graph authority | Installed instructions |
| Check evidence boundaries and compatibility limits | Known limitations |
| Inspect the shipped scope | Product scope |
| Inspect earlier acceptance and development history | Source provenance |
| Run checks or contribute to the kit | Contributing and contributor instructions |
Use a bounded Task with a recorded plan, explicit file ownership, and evidence for the change. Preserve existing safeguards, add relevant regression tests, and leave acceptance and merge decisions to the owner.
Start with CONTRIBUTING.md and this repository's AGENTS.md. These instructions govern contributions to the kit.
A contributor quick check, from this kit's checkout:
python3 -I .github/scripts/check-product.py
python3 -I .github/scripts/check-installer.py
git diff --checkThese are a starting subset; use the full validation instructions. Product CI runs quality and conformance checks without predecessor history or old Issue retrieval. Pinned lint-tool acquisition is a separate CI network step.
This project adapts Agentic Development Kit for GitHub Copilot. The frozen behavioral source and target adaptations are recorded in source parity. The logo is reused from that same frozen source revision; it is an external reference, not a claim of OpenAI endorsement.
Licensed under the MIT License. Your application's license remains yours; installing the kit does not replace it.