Reusable artifact-driven AI workflow framework for repositories with staged workflows, manifests, templates, and install tooling.
ai-workflow-framework provides a structured, reusable process for an AI-assisted task delivery lifecycle inside source repositories.
It standardizes how work moves through defined task-delivery stages such as intake, design, implementation, commit, and review, with optional downstream release/operations extensions, by using:
- stage-based workflow documents
- deterministic artifact manifests
- task and snapshot templates
- normalized intake scaffolding for chat-first and external-system requests
- starter scaffolding
- install and sync tooling
The goal is to make AI-assisted task delivery more consistent, reviewable, and portable across projects.
This framework is built around a few core principles:
- Artifacts over chat history: task state should be reconstructed from files, not conversation memory.
- Stage ownership: each workflow stage owns specific artifacts and should only update its allowed outputs.
- Deterministic context loading: each stage reads only the files declared by its manifest.
- Portable process: the same workflow structure can be reused across multiple repositories.
- Local task ownership: live task state stays in the consuming repository, not in the shared framework.
- Parallel task isolation: in-progress tasks should use dedicated git branches and worktrees.
framework/
workflows/
artifacts/
README.md
manifests/
templates/
starter/
artifacts/
tasks/
README.md
scripts/
install-framework.ps1
docs/
consuming-repo-layout.md
- Shared workflow stage documents
- Artifact contract documentation
- Stage manifests
- Reusable task templates
- Starter task scaffolding
- Installation and update tooling
- Usage guidance for consuming repositories
This repository should not contain live task state for consuming projects.
Keep these in each consuming repository:
.ai/AGENT-RULES.md.ai/artifacts/tasks/<task-id>/current/*.ai/artifacts/tasks/<task-id>/logs/*
The preferred model is to use this repository as a shared framework source and copy or sync its reusable assets into each consuming repository.
This avoids Git submodule friction while preserving a versioned source of truth.
A submodule-based setup is possible, but it is usually best to keep only shared framework assets in the submodule and keep all live task state local to the consuming repository.
Use the install script to copy the framework into a target repository:
.\scripts\install-framework.ps1 -TargetRepoPath C:\src\MySolutionAfter installation:
- Update
.ai/AGENT-RULES.mdfor the target repository. - Start stage 01 intake from chat or from an existing raw intake record.
- Let stage 01 create the task workspace and normalize the intake details.
- Continue through the intake workflow.
See INSTALL.md for setup details.
The framework defines a core task delivery lifecycle:
- Intake and specification
- Discovery and design
- Implementation
- Commit
- Quality and pull request
For most teams, the framework's normal scope ends here when the task is merged to main or is otherwise approved and ready to merge.
For repositories that intentionally keep release and operational follow-up inside repo-local artifacts, the framework also includes:
- Release and deploy
- Operate and improve
Each stage has:
- a workflow document
- a manifest describing required inputs
- explicit rules for allowed outputs
This framework helps teams:
- reduce ambiguity in AI-assisted work
- keep task state explicit and auditable
- improve handoff quality between stages
- reuse a consistent workflow across repositories
- avoid over-reliance on transient chat context
This template is set up for the MIT license.