> ## Documentation Index
> Fetch the complete documentation index at: https://docs.builddown.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Workflow template files and front matter
> How the workflow files synced to target repos work, the front matter keys they read from WORKFLOW.md and PLANNING.md, and how to run a resync.
**Experimental version.**
This is the latest in-development version of AI-Implement. Features may change without notice and behavior is not guaranteed. Switch to the [latest stable version here](/introduction).
When you sync AI-Implement to a target repo, it installs three 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 a gap analysis comment to the PR. 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](/latest/configuration/planning) for the full flow.
### `comment-trigger.yml`
Listens for `/ai-implement` comments on open pull requests. When a team member posts that comment, it dispatches `claude-implement.yml` with the existing PR number so Claude can address remaining gaps without opening a new branch.
### `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
Run the sync workflow manually to push the latest templates to a target repo:
```bash theme={null}
gh workflow run sync-workflow.yml -f target_repo=your-org/your-repo
```
This opens a pull request in the target repo with the updated workflow files. It will seed `WORKFLOW.md` and `PLANNING.md` only if those files do not already exist.
## `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.
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.
Model ID used for the post-PR gap analysis step. For `anthropic`, defaults to `claude-haiku-4-5-20251001` when omitted. For `bedrock`, defaults to the same value as `model`. Override this to use a faster or cheaper model for gap analysis.
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.
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.
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
```yaml theme={null}
---
model: claude-sonnet-4-6
gap_analysis_model: claude-haiku-4-5-20251001
setup: scripts/ci-setup.sh
verify: scripts/ci-verify.sh
teardown: scripts/ci-teardown.sh
---
```
## `PLANNING.md` front matter
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` |