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 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 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: 
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
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.
​
gap_analysis_model
string
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.
​
setup
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.
​
verify
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.
​
teardown
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
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
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:
VariableDescription
${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:
VariableDescription
${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