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 reviews it and posts what it finds as PR comments. The originating issue’s status and any related comments are updated separately by the orchestrator via its provider-callback mechanism.

`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.

Removed by sync

Older repos carry a third workflow, .github/workflows/comment-trigger.yml, which handled /ai-implement comments inside the repo. Sync deletes it — the orchestrator serves that trigger now, through its GitHub webhook. The deletion arrives in the same pull request as the workflow updates, so a repo that has not re-synced still has the file and still uses the old path.

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 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. The workflow lives in your AI-Implement repository rather than the target repo, so dispatch it from there:

gh workflow run sync-workflow.yml --repo your-org/AI-Implement -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

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 substitutes a fixed list of ${NAME} variables into the body of WORKFLOW.md with a regular expression — not with envsubst, so shell semantics don’t apply. Use any of them anywhere in the template. A brace-less $VAR is left untouched.

Any other ${UPPER_SNAKE} token is replaced with an empty string, so a shell example containing ${...} is silently emptied, with no error and no log line.

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 is substituted the same way, and the rules above apply to it too. Its full set, including the variables describing where the issue sits in a parent/child tree:

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

Optional 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`

Removed by sync

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

​Removed by sync

​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`

Removed by sync

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`