setup codex agenticapps workflow
- Repo stars 0
- Author repo skills-registry
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# setup-codex-agenticapps-workflow
This skill is the entry point for bootstrapping a fresh project with
the codex-workflow scaffolding. It applies the baseline migration
(`migrations/0000-baseline.md`) and any additional migrations that
have shipped between scaffolder versions, leaving the project at the
current scaffolder version.
## When to invoke
User asks to set up the workflow on a project that does not yet have
a `.codex/workflow-version.txt` file. The trigger skill's
`agentic-apps-workflow` does NOT auto-route to setup — setup is an
explicit, user-driven act because it modifies project-side files
(AGENTS.md, .planning/config.json, .codex/) that the user expects to
review.
## What this skill does
### Stage A — Pre-flight
1. **Verify Codex CLI.** `codex --version` must succeed.
2. **Verify scaffolder install.** Confirm
`${CODEX_HOME:-$HOME/.codex}/skills/agentic-apps-workflow/SKILL.md`
exists. If not, instruct the user to clone codex-workflow and run
`bash install.sh` from its root before retrying.
3. **Verify project state.**
- Project must be a git repo (`test -d .git`).
- Project must NOT already have `.codex/workflow-version.txt`. If
it does, route the user to `$update-codex-agenticapps-workflow`
and stop.
4. **Check optional gates.** Run the `optional_for` detection
commands from `0000-baseline.md` and record the user's choice for
each (e.g. Option A vs Option B install).
### Stage B — Gather placeholder values
5. **Ask the user** the questions in `0000-baseline.md` Step 1's
placeholder table:
- Project name
- Repo URL (autofilled from `git remote get-url origin` if
available; otherwise prompt)
- Client (internal / external name)
- Budget tier (free / paid / enterprise)
- Backend language (Go / Python / TypeScript / Rust / Other)
- Frontend stack (or "none" if backend-only)
- Database (or "none")
- LLM provider (anthropic / openai / google / other / none)
For optional values, accept defaults if the user says "default" or
skips:
- design-critique quality bar (default 90)
- impeccable-audit quality bar (default 90)
- QA viewports (default 1280, 390)
- DB blocking severity (default Critical, High)
### Stage C — Apply the baseline migration
6. **Walk `migrations/0000-baseline.md` step by step.** For each
step:
- Run the **idempotency check**. If it returns 0, log "skipped
(already applied)" and continue.
- Run the **pre-condition**. If it fails, error out with the
pre-condition's specific message.
- Show the user the **apply** block. In default-on-confirm
interactive mode, dry-run the whole chain first; in
`--no-confirm` mode, apply each step automatically.
- Apply the patch. For Step 1 (workflow-config.md), substitute
placeholders with the values from Stage B.
- On failure: prompt the user with retry / skip-with-warning /
rollback options per the atomicity contract in
`migrations/README.md`.
7. **Skip Step 6** (global AGENTS.md additions) if the user picked
Option B (per-project install) in Stage A's optional gate
detection.
### Stage D — Post-checks and commit
8. **Run all post-checks** from `0000-baseline.md`:
- `.codex/workflow-config.md` exists and has no unsubstituted
`{{...}}` placeholders
- `.planning/config.json` is valid JSON with the expected hook
keys
- `AGENTS.md` contains the `BEGIN: agentic-apps-workflow` marker
- `docs/decisions/README.md` exists
- `.codex/workflow-version.txt` reads `0.1.0`
9. **Atomic commit.** All baseline-migration changes go in a single
commit:
```bash
git add .codex/ .planning/ AGENTS.md docs/decisions/
git commit -m "chore: install codex-workflow v0.1.0"
```
10. **Surface follow-ups.** Tell the user:
- The project is now at `codex-workflow v0.1.0`
- Next step: run `$gsd-discuss-phase 1` to start a planning
session for the first phase
- Future scaffolder updates: run
`$update-codex-agenticapps-workflow` periodically; the skill
reads `.codex/workflow-version.txt` and applies pending
migrations
## Required evidence (per spec/06)
- `.codex/workflow-version.txt` exists with content `0.1.0`
- `.planning/config.json` is valid JSON with all `hooks` keys from
the template
- `AGENTS.md` contains the marker pair
`<!-- BEGIN: agentic-apps-workflow sections -->` ... `<!-- END: agentic-apps-workflow sections -->`
- `docs/decisions/README.md` exists
- The atomic commit is on the project's current branch with the
expected files staged
## Failure modes
- **Re-running on an installed project.** The pre-flight check
catches this; never auto-overwrite. Route to
`$update-codex-agenticapps-workflow`.
- **Scaffolder not installed.** Surface the install path; do not
silently skip steps that depend on the scaffolder.
- **Half-applied migration.** Per the atomicity contract, prompt
user (retry / skip / rollback). Do not auto-rollback without
consent — the user may prefer partial-state recovery.
- **Forgetting Step 6 distinction.** Option A (global) and Option B
(per-project) are mutually exclusive for this step. Skip Step 6
cleanly when the user picked Option B.
## Notes for the Codex host
- The default `$CODEX_HOME` is `~/.codex`. Migrations use the
`${CODEX_HOME:-$HOME/.codex}` form so users with a non-default
`$CODEX_HOME` get the same behavior.
- The `templates/` directory referenced from migrations lives at
`${CODEX_HOME:-$HOME/.codex}/skills/setup-codex-agenticapps-workflow/templates/`.
`install.sh` symlinks the scaffolder's top-level `templates/` to
this path so migrations can `cp` from a stable location.
- "Project name detection" can also pull from
`package.json::name`, `pyproject.toml::project.name`,
`Cargo.toml::package.name` — surface those as a prefilled
default in the question rather than always asking from scratch.
---
> Source: [agenticapps-eu/codex-workflow](https://github.com/agenticapps-eu/codex-workflow) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
Sections and files
Listed in source order.
sections -> When to invoke → What this skill does → Stage A — Pre-flight → Stage B — Gather placeholder values → Stage C — Apply the baseline migration → Stage D — Post-checks and commit
terms -> Verify Codex CLI. · Verify scaffolder install. · Verify project state. · Check optional gates. · Ask the user · Walk migrations/0000-baseline.md step by step. · idempotency check · pre-condition
files/cmd -> migrations/0000-baseline.md · .codex/workflow-version.txt · agentic-apps-workflow · codex --version · ${CODEX_HOME:-$HOME/.codex}/skills/agentic-apps-workflow/SKILL.md · bash install.sh · test -d .git · $update-codex-agenticapps-workflow
body sha256 -> f5f746389cc3
When to invoke
User asks to set up the workflow on a project that does not yet have a
.codex/workflow-version.txtfile. The trigger skill'sagentic-apps-workflowdoes NOT auto-route to setup — setup is an explicit, user-driven act because it modifies project-side files (AGENTS.md, .planning/config.json, .codex/) that the user expects toStage A — Pre-flight
Verify Codex CLI.
codex --versionmust succeed. Verify scaffolder install. Confirm${CODEX_HOME:-$HOME/.codex}/skills/agentic-apps-workflow/SKILL.mdexists. If not, instruct the user to clone codex-workflow and runbash install.shfrom its root before retrying.Stage B — Gather placeholder values
Ask the user the questions in
0000-baseline.mdStep 1's placeholder table: Project name Repo URL (autofilled fromgit remote get-url originif available; otherwise prompt)Stage C — Apply the baseline migration
Walk
migrations/0000-baseline.mdstep by step. For each step: Run the idempotency check. If it returns 0, log "skipped (already applied)" and continue. Run the pre-condition. If it fails, error out with theStage D — Post-checks and commit
Run all post-checks from
0000-baseline.md:.codex/workflow-config.mdexists and has no unsubstituted{{...}}placeholders.planning/config.jsonis valid JSON with the expected hook keys