setup-workflow

name	setup-workflow
description	Configure a repository for this Codex GitHub-first delivery workflow. Use once before to-prd, to-issues, triage, implement, tdd, diagnosing-bugs, or acceptance, or whenever a repo lacks docs/agents issue tracker, triage labels, domain docs, verification command, or GitHub/local fallback configuration.

Setup Workflow

Configure the per-repo facts that the workflow skills need before they create PRDs, split issues, implement slices, triage changes, diagnose bugs, or run acceptance.

This skill is prompt-driven. Explore first, present a concise draft, confirm with the user, then write.

Process

1. Explore

Inspect the repo without changing business code:

• git remote -v and .git/config to identify GitHub remotes.
• gh auth status and gh repo view when a GitHub remote exists.
• Root AGENTS.md and CLAUDE.md; check for an existing ## Agent workflow or legacy ## Agent skills block.
• Existing docs/agents/.
• CONTEXT.md, CONTEXT-MAP.md, root docs/adr/, and context-local docs/adr/.
• Test/build/lint/typecheck scripts, task runners, Makefiles, package manifests, and CI config.
• Existing .github/ISSUE_TEMPLATE/ and .github/pull_request_template.md.
• .scratch/, if present, as a local markdown issue tracker signal.

If GitHub is unavailable or permissions are missing, explain the blocker and offer local markdown fallback.

2. Confirm Decisions

Ask only for decisions that cannot be inferred safely. Keep each question short.

Issue tracker

Default to GitHub Issues when the repo has a GitHub remote and gh can access it. Otherwise use local markdown under .scratch/.

For GitHub, ask whether external PRs should be treated as a request surface. Default: no.

Triage labels

Use these canonical roles unless the repo already uses different label names:

• bug
• enhancement
• audit
• needs-triage
• needs-info
• ready-for-agent
• ready-for-human
• wontfix

Each triaged item should have one category label and one state label. The default Type to category mapping is:

• bug -> bug
• audit -> audit
• PRD, slice, change -> enhancement

For GitHub, offer to create any missing labels after the user confirms.

Domain docs

Choose one:

• Single-context: root CONTEXT.md and docs/adr/.
• Multi-context: root CONTEXT-MAP.md points to per-context CONTEXT.md files.

Proceed silently if these files do not exist yet. Domain docs are created later only when domain language or architectural decisions actually crystallize.

Verification commands

Summarize discovered commands and CI jobs. Record unknowns explicitly instead of inventing commands.

Capture:

• Unit/integration/e2e test commands.
• Typecheck, lint, format, build commands.
• The smallest useful check for one slice.
• The broadest reasonable regression check before acceptance.
• CI workflow names or status checks, when visible.

3. Draft

Show a draft before writing:

• The root agent block to add or update.
• docs/agents/issue-tracker.md.
• docs/agents/triage-labels.md.
• docs/agents/domain.md.
• docs/agents/verification.md.
• For GitHub issue tracker only: .github/ISSUE_TEMPLATE/agent-work-item.md.
• For GitHub issue tracker only: .github/pull_request_template.md.

Let the user correct the draft before editing files.

4. Write

Prefer Codex conventions:

• If AGENTS.md exists, update it.
• Else if CLAUDE.md exists and the user wants to keep it as the shared agent entry, update it.
• Else create AGENTS.md after showing the draft.

If an ## Agent workflow block exists, update it in place. If only a legacy ## Agent skills block exists, update that block in place unless the user asks to rename it. Do not duplicate blocks.

Use these bundled templates:

• issue-tracker-github.md
• issue-tracker-local.md
• triage-labels.md
• domain.md
• verification.md
• github-issue-template.md
• github-pull-request-template.md

When GitHub Issues is the configured tracker, create or update:

• .github/ISSUE_TEMPLATE/agent-work-item.md
• .github/pull_request_template.md

Do not overwrite substantial existing templates without showing the merge plan first. If the repo already has templates, preserve project-specific sections and add only the missing workflow fields.

The root block should stay compact:

## Agent workflow

### Issue tracker

[one-line summary]. See `docs/agents/issue-tracker.md`.

### Triage labels

[one-line summary]. See `docs/agents/triage-labels.md`.

### Domain docs

[one-line summary]. See `docs/agents/domain.md`.

### Verification

[one-line summary]. See `docs/agents/verification.md`.

5. Finish

Tell the user:

• Which files were created or updated.
• Whether GitHub is ready or local markdown fallback is active.
• Which verification commands are known.
• What remains blocked or unknown.

Do not implement product code during setup.