setup codex agenticapps workflow

AI Community

Skill notes

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

Stage A — Pre-flight

Verify Codex CLI. codex --version must succeed. 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.

Stage B — Gather placeholder values

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)

Stage C — Apply the baseline migration

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

Stage D — Post-checks and commit

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

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
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.

Author source file SKILL.md

# 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 -->

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.