Skip to main content
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.
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. The workflow filenames stay the same for Claude and Codex. Stage settings select the agent and execution settings for configured projects; these files still supply prompts and hooks.

​
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 the implementation agent. After the pipeline opens 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. The planning agent 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 the planner 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-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:

​
WORKFLOW.md front matter

The YAML front matter block at the top of WORKFLOW.md (between the --- delimiters) is stripped before the prompt reaches the agent. Hooks apply to both agents. The model key selects a model only for legacy projects.
​
string
Model ID for legacy implementation runs. Configured projects use the implementation stage model.For legacy Bedrock runs, supply a compatible model ID or inference-profile ARN. The workflow does not check model availability before invocation.
​
string
Path to a shell script (relative to the repo root) run before the implementation agent starts. Use this to install dependencies, set up test databases, or do any other environment preparation.
​
string
Path to a shell script run after an approved push. 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 implementation or verification fails. Use this to clean up resources such as temporary databases or test containers.

​
Example WORKFLOW.md front matter

​
PLANNING.md front matter

​
string
Model ID for legacy planning runs. Configured projects use the planning stage model. For legacy Bedrock runs, supply a compatible model explicitly.

​
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 substitution in PLANNING.md

PLANNING.md is substituted the same way, and the rules above apply to it too. It takes the common issue fields, plus three describing the issue’s place in the tree: