GitHub-native, Human-on-the-Loop workflows for development with Codex.
Quick start · Prerequisites · How it works · Skills · Safety and status · Documentation
Give Codex a repeatable way to prepare context, plan, implement, and return evidence. Keep plans and decisions in GitHub instead of relying on one chat.
Codex works within a defined Task. Humans set direction, decide exceptions, and retain agreement, acceptance, and merge authority. The kit's Skills, instructions, templates, and helpers support this workflow without replacing 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.
Prerequisites are cumulative; the IDs below bind this table to the machine-readable prerequisite registry.
| Tier | Prerequisites added at this tier | Reach |
|---|---|---|
| Tier 0 — Install & inspect | GitHub repository and local checkout (github-checkout); Git (git); Bash 3.2+, with Git for Windows / Git Bash on Windows (bash); jq (jq); gh (gh), authenticated with access to the target repository (repository-access) |
Install/stage the scaffold and read its documentation. |
| Tier 1 — Onboard & run Tasks | ChatGPT Codex desktop app (codex-desktop); prepared specification context (spec-context); adopter Codex project (codex-project); scaffold landed on the remote default branch before onboarding (remote-scaffold) |
Complete onboarding and run authorized Tasks locally. |
| Tier 2 — Full operation | Projects read:project / project permissions (projects-scope); a board or a recorded scoped exception for environmental inability or explicit owner decline (projects-board-or-exception) |
Operate the roadmap and perform required Task close-out. |
Tier 1: the desktop app is required for this OSS, not just for this tutorial. Use the desktop app for onboarding, coordination and development; Codex CLI or the IDE extension alone is unsupported. Terminal installers and helpers neither replace this requirement nor check whether the app is installed.
For full adoption, prepare specification context and create/select the adopter's Codex project below. Tier 0 installation/inspection can precede Tier 1 readiness but does not complete onboarding. See step 1 for platform-specific installation utilities.
Tier 2: the GitHub Projects roadmap is required by default, with durable scoped
exceptions when the environment cannot create/use it or the owner explicitly
declines Projects. It needs Projects access: read:project
for queries and project for creation/updates with classic/OAuth credentials
(GitHub's scope guidance).
Repository access alone is insufficient. If scopes are missing, the owner can
run gh auth refresh -s project for stored gh credentials; environment tokens
or other credential types may need their own permission update. The kit reports
the gap early and asks separately before creating a board. It never refreshes
credentials automatically. Record a declined/unavailable exception on the
relevant Epic/Tasks; Issue-based planning and development can continue.
Creation and date application need their applicable authorization. A pending
answer or a date-only defer/decline is not a Project exception: otherwise
authorized work may proceed, but required close-out stays pending. Before a
Task is reported complete, verify Kind Task and both authorized dates on its
exact Project item, or cite its exception. See the
close-out procedure.
For a one-command read-only diagnosis, use Python 3.11+ and a reviewed kit source checkout; these diagnostics are not installed payload:
python3 -I /path/to/reviewed-kit/.github/scripts/check-prerequisites.py /path/to/adopterThe target defaults to the current directory. Missing prerequisites name their impact and remedy; desktop/context/project state needs explicit procedural confirmation. Diagnostics do not install, authenticate, grant consent or block onboarding. The introduction guide covers exit statuses, the seven-point material check and onboarding evidence PR lead-time records. The checkout is only for diagnostics; adoption uses the public installer.
Use the required desktop app with your local application repository. If it has a product selector, select Codex, not ChatGPT Chat or Work, for installation and development.
- Prepare specification context before using the kit. Use ChatGPT Chat to clarify requirements interactively, or Work to assemble a reviewable specification from notes and sources. Record the goal, intended users, scope/non-goals, constraints, acceptance criteria, and unresolved questions. Review it and reuse suitable existing specifications. Prepare this handoff before adoption; the installer does not validate its contents and no external connector is required.
- First in Codex, create or select your project. Attach your application's local Git repository and make its root the project's primary folder. This adopter repository is not the kit's source checkout. Prepare or clone it first if needed; an app project does not replace Git setup. Start a local chat in that project and confirm its working directory before step 1 below.
- Bring the prepared context with you. Save it in a readable file, attach it, or paste relevant text when the onboarding Skill asks for material. Give paths for documents already committed in the adopter repository. Do not assume Chat/Work history, a ChatGPT project, or a chat link automatically supplies context to Codex. Share only authorized material; drafts become approved agreements only through the kit's human review process.
A Codex project selects the execution context. It is not a ChatGPT preparation project or a GitHub Projects board. See the detailed preparation checklist and official guidance on desktop mode selection, local project folders, and Chat versus Work.
Run the public one-command installer below in a terminal at the adopter root selected in your Codex desktop project: an existing Git repository that no other agent or person is changing concurrently. To adopt the kit, use this route; do not clone it or run installer scripts from a kit checkout.
| Installation route | Additional utilities |
|---|---|
| macOS / Linux installation | curl, find, standard Unix utilities (including GNU/BSD stat), and sha256sum or shasum |
| Windows installation | PowerShell and the Unix utilities supplied by Git for Windows / Git Bash |
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 | iexDownloading the public kit needs no GitHub login; operating it still requires
the authenticated gh and other workflow prerequisites above. The Windows
entry uses Git Bash, not WSL; it has synthetic-test coverage, but native Windows
installation has not been measured.
The installer resolves a source revision, validates and installs the payload, and stages only newly installed files. It preserves 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,
or PowerShell flags, 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 be staged. Commit only reviewed adoption changes and land them on the remote default branch through your normal approval process 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.
Follow this public Quick start for installation and staging: the entry stages
new files. The preserved guide's no-staging statement describes the internal
engine, not the public installer.
Before invoking the Skill, open or select the adopter checkout in Codex—
your project, not the kit's repository—and start a new local desktop chat
in the prepared project to read the installed files. Have your specification
context ready for the material question. Answer every pending question,
including model preference, explicitly (auto is a choice, not a timeout default).
In the desktop project chat, invoke the installed Skill:
$project-onboarding
If your desktop app version lacks that invocation, use this explicit installed-file fallback in the same chat:
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 in every app version.
Onboarding inventories the project, verifies existing commands, tunes its 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 ordinary development.
After the reviewed installation reaches the remote default branch, onboarding runs canonical label setup and drafts phase Epic Issues for review when you supply a goal or material. These writes are distinct from optional Ruleset setup: explicitly choose Enable now, Create disabled, or Skip. Writes 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.
To connect Task records to PR checks, a separate opt-in adopter CI companion previews three addon files for explicitly named application checks. It requires a supported existing workflow, preserves application CI and the Git index, and adds no required-check settings. Accept its installation before separately considering check activation; it is outside the legacy 47-file update path.
For an existing codebase, start with characterization tests for the area you intend to change. This onboarding Skill legacy path establishes an observed-behavior baseline before feature work. For example:
Use the installed kit workflow to add characterization tests for the existing
report page. Capture its current behavior without adding a feature or changing
application behavior.
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.
The illustrative worked example covers a first characterization Task with locally runnable reference tests. It is neither accepted live work nor installed into your project.
Review the Task, diff, and evidence—not only the final chat message—then accept, redirect, or reject. Use retrospectives when repeated friction suggests a reusable improvement. After accepting the characterization baseline, plan a small feature Task separately. For a new codebase, agree on initial behavior and tests in its first bounded Task.
No kit clone is needed. Supply full 40-character commit IDs for the installed
version (FROM) and reviewed new version (TO). Use the previous installation's
recorded source-commit or accepted adoption record for FROM; if unknown,
inspect that record before updating. Choose a new recovery directory outside your project
with an existing parent. Run from your project root with exclusive ownership
during the update.
FROM=FULL_OLD_COMMIT_SHA
TO=FULL_NEW_COMMIT_SHA
RECOVERY=/path/to/new-private-recovery
set -o pipefail
curl -fsSL https://raw.githubusercontent.com/mochan-tk/agentic-dev-kit-for-codex/main/.github/scripts/scaffold-update.sh | bash -s -- --from "$FROM" --to "$TO" --recovery "$RECOVERY"The default previews without changing project files, the index, or the requested recovery directory. Apply the explicit update with:
curl -fsSL https://raw.githubusercontent.com/mochan-tk/agentic-dev-kit-for-codex/main/.github/scripts/scaffold-update.sh | bash -s -- --from "$FROM" --to "$TO" --recovery "$RECOVERY" --applyPowerShell with Git Bash uses the same inputs and default preview:
$From = 'FULL_OLD_COMMIT_SHA'
$To = 'FULL_NEW_COMMIT_SHA'
$Recovery = 'D:\private-recovery\new-update'
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/mochan-tk/agentic-dev-kit-for-codex/main/.github/scripts/scaffold-update.ps1))) --from $From --to $To --recovery $Recovery
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/mochan-tk/agentic-dev-kit-for-codex/main/.github/scripts/scaffold-update.ps1))) --from $From --to $To --recovery $Recovery --applyKnown-old engine files update; tuned instructions, instance records, existing seed files and unrelated work are preserved. Unknown engine edits refuse the whole update. Nothing is staged, committed or pushed. Keep the private recovery directory at its original location, including after a failed apply. See offline rollback and fixed-entry selection before changing or deleting retained recovery inputs. Native Windows remains unmeasured; updates are explicit and do not detect installed versions.
The fixed-revision companion commands observe GitHub governance, check planned worktree actions, or validate connector definitions. Choose a check and supply actual inputs; each Bash command downloads the complete unchanged helper, verifies its recorded SHA-256, and runs it without installing extra project files.
Governance uses your existing authenticated gh for GET-only observations;
the other checks are local after downloading. No command repairs settings,
claims ownership, activates connectors or grants permission to push. Missing
evidence remains non-success. A successful check is not runtime qualification.
GitHub is the durable work record. Codex sessions execute work without replacing the Issue graph or human acceptance.
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 required Codex desktop app, 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 are instructions, not authenticated identities or guaranteed native role selection. A GitHub Projects board is required by default with the two recorded exceptions above; the Issue graph remains authoritative. A board match is verification evidence, not acceptance or merge authority.
Routine, scoped work can follow the agreed plan without per-edit human approval. Ambiguity, high risk, scope changes, and insufficient evidence need human judgment. The owner retains agreement and merge authority.
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 current step's Skill; 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 | Explicit old/new commit IDs support a one-command update with preserved customizations and retained offline operation rollback; no 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 | The ChatGPT Codex desktop app is required; CLI-only/IDE-only operation is unsupported. Evidence remains version/path-specific; automatic Skill discovery and cross-client parity are not promised |
| Product and release | A source-first workflow kit with bounded product tests; native Windows and cross-client runtime parity remain unmeasured |
Run the explicit governance, worktree and connector companions from a reviewed kit checkout or the verified no-clone commands; the one-command entry does not install them. The consent-gated failure reporter also has a verified no-clone draft/send guide. For manual text, use the public feedback form and review its privacy warning before submitting. Installation failures print fixed links to these routes; reporting is a separate explicit action. See the helper and procedure guide.
This repository's clean product Git history preserves the accepted predecessor's 47-file payload and installer engine. product scope and known limitations describe current behavior and evidence boundaries. Earlier acceptance, research and unfinished runtime/release work remain in the predecessor records. The dated evidence status separates baseline CI, synthetic conformance, the accepted historical desktop exercise and unmeasured behavior. Historical acceptance does not establish live behavior of later revisions.
| You want to… | Read |
|---|---|
| Install, select a revision, update, or recover an operation | Installation guide |
| Check governance, worktrees or connector definitions without a kit clone | Read-only companion commands |
| Draft installer feedback without a clone or share public-safe manual feedback | Feedback guide and public form |
| Opt in to separate Task metadata, retarget freshness and control drift checks | Adopter CI companion |
| Review retrospective signals, official content checkpoints and feedback | Ongoing improvement companions |
| Observe open PR checks and reviews manually | Manual PR monitor |
| Opt in to a manual-order chat-tree display inside an existing Codex project | Desktop chat-tree guide |
| Understand the installed instructions and workflow | Installed workflow guide and installed AGENTS |
| Walk through a first characterization Task with runnable reference tests | Illustrative worked example |
| Understand Issue-graph authority | Installed instructions |
| Check evidence boundaries and compatibility limits | Known limitations |
| Distinguish tested behavior, historical live acceptance and unmeasured claims | Dated evidence status |
| 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, recorded plan, explicit file ownership, and change evidence. Preserve safeguards, add relevant regression tests, and leave acceptance and merge to the owner.
Start with CONTRIBUTING.md and AGENTS.md, which govern kit contributions.
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 --checkFollow the full validation instructions beyond this starting subset. 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 reuses that same revision as an external reference without claiming OpenAI endorsement.
Licensed under the MIT License; installation does not replace your application's license.
