Workflow template files and front matter

When you sync AI-Implement to a target repo, it installs two GitHub Actions workflow files and two prompt template files into that repo. The workflow files are managed by AI-Implement and should not be edited directly in the target repo. The prompt template files are yours to customize — after the initial sync, AI-Implement never overwrites them.

Files installed by sync

`claude-implement.yml`

The main implementation workflow, placed at .github/workflows/claude-implement.yml in the target repo. The orchestrator dispatches this workflow whenever an issue is ready to process — Linear issues with the AI-Implement label, or Jira issues with AI-Implement Status set to Ready. It reads WORKFLOW.md from the repo root, substitutes issue variables into it, and passes the result to Claude Code as the implementation prompt. After Claude creates a PR, the workflow posts an automated merge-readiness review to the PR. The originating issue’s status and any related comments are updated separately by the orchestrator via its provider-callback mechanism. A comment on the PR that starts with /ai-implement is handled by the orchestrator itself, not by a workflow file — it checks the commenter’s repo permission and dispatches claude-implement.yml against the existing PR branch so Claude can address remaining gaps without opening a new branch. This needs the GitHub App’s webhook configured; see Create a GitHub App.

`claude-plan.yml`

The planning workflow, placed at .github/workflows/claude-plan.yml. Dispatched before implementation when planningEnabled=true on the team mapping. Claude reads the codebase in read-only mode and produces structured planning comments that get posted to the originating issue. The planning context is then included automatically in the implementation prompt when claude-implement.yml runs. See AI planning phase for the full flow.

`WORKFLOW.md`

Your implementation prompt template, placed at the root of the target repo. The sync workflow seeds this file once. After that, it is yours — future syncs will not overwrite it. Customize the “Repo context” and “Quality checklist” sections for your stack and standards.

`PLANNING.md`

Your planning prompt template, seeded once in the same way as WORKFLOW.md. Customize the “Repo context” section to tell Claude which directories and patterns matter most for your codebase.

Security posture

The synced workflow files use two defensive practices worth knowing about:

Pinned action versions — every third-party GitHub Action they call is pinned to a specific commit SHA rather than a version tag. Updates ship through the next sync-workflow.yml run rather than auto-applying when upstream releases a new tag.
Token masking — when the orchestrator passes runner-callback tokens (run_token and run_progress_token) to a run, the workflow registers them with ::add-mask:: before the runner uses them. If a token accidentally surfaces in workflow output, GitHub displays it as ***.

Syncing templates to a repo

Within the admin UI, each project row has a Sync workflows action. This is the usual way workflows are synced on demand. Editing and saving a project also syncs its workflow templates if other changes need to be made. Either route opens a pull request in the target repo with the updated workflow files. It seeds WORKFLOW.md and PLANNING.md only if those files don’t already exist. A command-line equivalent is available if you’re scripting against a self-hosted orchestrator:

gh workflow run sync-workflow.yml -f target_repo=your-org/your-repo

`WORKFLOW.md` front matter

The YAML front matter block at the top of WORKFLOW.md (between the --- delimiters) is stripped before the file is sent to Claude. Use it to configure model selection and lifecycle hooks.

string

Model ID passed verbatim to claude-code --model for implementation runs. Required when provider=bedrock; optional for anthropic (default: claude-sonnet-4-6). For Bedrock, use a model ID such as anthropic.claude-sonnet-4-6-20250805-v1:0 or an inference-profile ARN. The workflow passes this value through without validation — typos fail fast at Claude invocation time with a clear error.

string

Reserved — not currently read. The seeded WORKFLOW.md ships this key commented out, and the front matter parser accepts it, but no step consumes it.The post-push review runs on the same model as the rest of the run — the model value above, or claude-sonnet-4-6 when that is unset.Setting it has no effect, so it cannot be used to shift the review onto a cheaper model.

string

Path to a shell script (relative to the repo root) run before Claude starts. Use this to install dependencies, set up test databases, or do any other environment preparation.

string

Path to a shell script run after Claude succeeds. Use this to run tests, linters, or any post-implementation quality checks. If this script exits non-zero, the workflow job fails.

string

Path to a shell script run always — even if the Claude step or the verify step fails. Use this to clean up resources such as temporary databases or test containers.

Example `WORKFLOW.md` front matter

---
model: claude-sonnet-4-6
setup: scripts/ci-setup.sh
verify: scripts/ci-verify.sh
teardown: scripts/ci-teardown.sh
---

`PLANNING.md` front matter

string

Model ID for planning runs. Follows the same rules as the model field in WORKFLOW.md: required for bedrock, optional for anthropic (default: claude-sonnet-4-6).

Variable substitution in `WORKFLOW.md`

After stripping front matter and HTML comments, the workflow runs envsubst on the body of WORKFLOW.md. You can use these variables anywhere in the template:

Variable	Description
`${ISSUE_IDENTIFIER}`	Ticketing-system identifier — e.g. `ENG-42` (Linear) or `PROJ-456` (Jira)
`${ISSUE_TITLE}`	Issue title
`${ISSUE_DESCRIPTION}`	Full issue description in Markdown
`${ISSUE_ID}`	Internal identifier — Linear’s UUID or Jira’s issue key
`${PR_NUMBER}`	Existing PR number on gap-fill runs; empty on the first implementation run

Variable substitution in `PLANNING.md`

PLANNING.md supports the following variables in addition to the common issue fields:

Variable	Description
`${ISSUE_IDENTIFIER}`	Ticketing-system identifier — e.g. `ENG-42` (Linear) or `PROJ-456` (Jira)
`${ISSUE_TITLE}`	Issue title
`${ISSUE_DESCRIPTION}`	Full issue description in Markdown
`${ISSUE_ID}`	Internal identifier — Linear’s UUID or Jira’s issue key
`${PARENT}`	Parent issue as `- IDENTIFIER: Title`, or `None` if there is no parent
`${SIBLINGS}`	Other children of the parent issue, newline-separated, or `None`
`${DEPENDENCIES}`	Related issues as `- [type] IDENTIFIER: Title`, newline-separated, or `None`

Get Started

Setup

Configuration

Providers

Customize

Reference

Workflow template files and front matter

Files installed by sync

`claude-implement.yml`

`claude-plan.yml`

`WORKFLOW.md`

`PLANNING.md`

Security posture

Syncing templates to a repo

`WORKFLOW.md` front matter

Example `WORKFLOW.md` front matter

`PLANNING.md` front matter

Variable substitution in `WORKFLOW.md`

Variable substitution in `PLANNING.md`

​Files installed by sync

​claude-implement.yml

​claude-plan.yml

​WORKFLOW.md

​PLANNING.md

​Security posture

​Syncing templates to a repo

​WORKFLOW.md front matter

​Example WORKFLOW.md front matter

​PLANNING.md front matter

​Variable substitution in WORKFLOW.md

​Variable substitution in PLANNING.md

Files installed by sync

`claude-implement.yml`

`claude-plan.yml`

`WORKFLOW.md`

`PLANNING.md`

Security posture

Syncing templates to a repo

`WORKFLOW.md` front matter

Example `WORKFLOW.md` front matter

`PLANNING.md` front matter

Variable substitution in `WORKFLOW.md`

Variable substitution in `PLANNING.md`