A portable workflow protocol for AI coding agents: context, persistent memory, task state, and handoffs in plain Markdown.
English | Türkçe
AI4UP gives development agents a consistent way to discover a project, retain verified knowledge, track unfinished work, and resume after a context reset or agent handoff. It is designed for OpenAI/Codex workflows and remains independent of programming languages, frameworks, and project types.
The protocol uses files your team can read, review, and version. There is no required database, API key, package manager, or agent framework. The included installer runs on Windows PowerShell 5.1; the Markdown protocol itself is portable to other environments.
- Recover context: keep the objective, completed actions, evidence, and next step across sessions.
- Remember what matters: retain reusable facts with sources, scope, and recheck conditions.
- Keep decisions traceable: record consequential choices without requiring an ADR for every edit.
- Load less context: start with three files and retrieve deeper references only when relevant.
- Coordinate agents: define bounded assignments, write ownership, integration, and handoff procedures.
- Adapt through discovery: derive commands and verification from the actual project, without a type catalog.
This is a development workflow kit, not an agent runtime. It does not launch agents, synchronize memory, or invoke native compaction by itself. An agent with file access follows the protocol; API applications must explicitly supply the relevant files as context. No model performance improvement is claimed without evaluation.
Clone the repository or download its complete source archive, then open Windows PowerShell in the kit directory:
git clone https://github.com/muhammedalikutbay/AI4UP.git
cd AI4UP
# Preview without creating files.
.\Initialize-Project.ps1 -TargetPath 'C:\Projects\MyProject' -WhatIf
# Install into a new folder or an existing project without protocol files.
.\Initialize-Project.ps1 -TargetPath 'C:\Projects\MyProject' -ProjectName 'My Project'Replace the example target with your actual project root. ProjectName is optional and defaults to
the target folder name. Keep templates/ beside the installer; copying only the script is insufficient.
Start a fresh agent session at the target project root and give it a task:
Read AGENTS.md, .ai/PROJECT.md, and .ai/STATE.md. Inspect the project to determine its actual tools, commands, and constraints. Retrieve relevant persistent knowledge and complete this task with verification: ...
No project type or profile is required. The agent inspects documentation, configuration, and source files
and records the actual working methods in .ai/PROJECT.md. For an empty project, it establishes the
purpose and requirements before choosing technology. A new language or tool does not require extending
the protocol. The installer does not install application dependencies.
The shipped instructions default to Turkish user-facing communication and English technical records.
Change the language preference in your project's AGENTS.md if needed; it is independent of the workflow.
flowchart LR
A[Read instructions and project state] --> B[Retrieve relevant knowledge]
B --> C[Execute and verify]
C --> D[Save state and reusable findings]
D --> E[Resume or hand off]
E --> A
The installer creates 11 files. Normal startup reads the first three; the others are retrieved on demand.
| File | Purpose |
|---|---|
AGENTS.md |
Canonical instructions, startup sequence, execution and delivery rules |
.ai/PROJECT.md |
Purpose, actual tools, commands, constraints, and verification methods |
.ai/STATE.md |
Active objective, completed work, evidence, blockers, and next action |
.ai/MEMORY.md |
Persistent project facts with sources, scope, and freshness information |
.ai/DECISIONS.md |
Consequential choices, alternatives, rationale, and revisit conditions |
.ai/KNOWLEDGE.md |
Index of deeper references |
.ai/reference/WORKFLOW.md |
Task lifecycle, context management, recovery, and agent coordination |
.ai/reference/RECORDS.md |
Optional task/handoff formats and reusable session prompts |
.ai/reference/OPENAI.md |
Codex/API boundaries, model choices, and native compaction considerations |
.ai/reference/SOURCES.md |
Official sources and the design choices they informed |
.ai/reference/EVALUATION.md |
Scenarios for evaluating protocol or model changes |
A small fix needs no separate task document or decision record. Larger efforts can create .ai/tasks/,
.ai/handoffs/, and .ai/archive/ when useful. Existing issue trackers and project documentation remain
in place; link to them instead of maintaining duplicate sources of truth.
Describe the work you want done. The agent updates task state at meaningful milestones, promotes verified reusable findings to memory, and records important decisions. A new session reads that state, checks it against the actual files, and continues. Memory travels with the project; it does not automatically spread to other projects or account-level memory.
Before switching sessions, you can ask:
Save the task state and pending operations so another session can continue.
For parallel work, explicitly request delegation:
Delegate independent work to subagents, assign exclusive write ownership, and verify the integrated result.
Availability depends on the host and its tools. One lead owns integration; work touching the same file or shared application session is serialized. A handoff document alone does not start another agent.
Version 1.1.0 removes profile selection. Remove -Profile from earlier installation commands. When
merging an older installation, preserve useful project-specific additions from PROFILES.md in
PROJECT.md, then remove the obsolete catalog and its references. Preserve active tasks and memory.
The installer stops before writing if AGENTS.md, AGENTS.override.md, Agent.md, or .ai already
exists. Generate into a separate staging folder first:
.\Initialize-Project.ps1 -TargetPath 'C:\Projects\ProtocolDraft' -ProjectName 'Existing Project'Compare the draft with the project's files. Consolidate applicable instructions in one root AGENTS.md
and preserve existing state. Inspect the effective scope of any nested instruction or override files.
Use the same approach for upgrades: compare templates instead of replacing populated records with blank ones.
The protocol version is recorded in AGENTS.md.
Other project files and an existing CLAUDE.md are preserved. If another agent client needs a different
entry point, use its supported mechanism to reference the canonical AGENTS.md; avoid duplicating the rules.
This installer does not create client-specific adapters.
Installation uses no network, does not initialize Git, and does not change global agent configuration. Files are written as UTF-8 without a BOM. Filesystem roots and linked target directories are rejected. Existing destination files are never overwritten.
Disk/permission failures or concurrent external changes can leave newly created partial output; the error reports successfully written files for inspection. The installer does not implement transactional rollback or a concurrent installation lock. Run one installer per target.
Version-control shareable .ai records for team and session continuity. Keep passwords, access tokens,
and private customer data out of them. Use your project's existing artifact and .gitignore conventions
for large or temporary evidence; the protocol does not modify those automatically.
.\tests\Smoke.ps1The smoke test checks installed output, relative links, encoding, existing-file preservation, preview behavior, and invalid destinations. GitHub Actions runs it on Windows PowerShell for pushes and pull requests. It does not establish model adherence or performance. Use the behavior evaluation scenarios for those comparisons.
The protocol was informed by official documentation on instruction discovery, compaction, and agent orchestration. The file layout is an AI4UP design choice, not an official OpenAI standard. AI4UP is an independent project. See the complete source register.
This repository's root AGENTS.md and .ai/ describe work on AI4UP itself. The distributable source is
under templates/; .template.md files are template data, not active instructions for this repository.
Bug reports, clearer instructions, translations, and evidence from real agent workflows are welcome. Read CONTRIBUTING.md, then open an issue or submit a focused pull request.
MIT — Copyright (c) 2026 Muhammed Ali KUTBAY.